# ThousandEyes Documentation

This is the documentation site for the Cisco ThousandEyes network intelligence platform.

#### Customer Support

[Click here](https://app.thousandeyes.com/sfdc/community/home/?communityTabId=Cases\&communityObjectId=New&) to open a case with the ThousandEyes Customer Engineering team.

#### ThousandEyes Platform

[Click here](https://app.thousandeyes.com/login?fwd=%2Fdashboard%2F%3FdashboardId%3D0) to go to the ThousandEyes platform.

#### ThousandEyes Blog

Read recent posts [here](https://blog.thousandeyes.com/).


# Changelog

## 2026-07-09

### Heatmap Dashboard Widget

You can now add a **Heatmap** widget to custom dashboards. The widget shows a color-coded matrix where each cell represents one combination of a row dimension and a column dimension, such as **Test** by **Agent**. Cell color shows how the value compares with other cells in the same widget for the dashboard time range, helping you scan for hotspots and outliers across your deployment without opening each test or agent separately.

![Heatmap dashboard widget example](/files/a6cbwCdubv0mpbyxWHdE)

Use a heatmap when you need to compare two dimensions at once. A single heatmap can replace a large grid of separate **Number** or **Color Grid** widgets for questions such as which agents are slow on which tests, or how interfaces compare across devices.

For more information, see [Dashboard Widgets](https://docs.thousandeyes.com/product-documentation/dashboards/dashboard-widgets#heatmap-widget).

### Pie Chart and Stacked Area: Stack by Submetrics or by Group

**Pie** and **Stacked Area** widgets now support metrics from all data sources in the metric picker.

For composite metrics, such as **HTTP Response Time**, the default is **Stack By Submetric**. In widget settings, you can switch to **Single Stacked Chart** to combine submetric components and divide the chart by your **Group By** dimension, such as **Test**, **Agent**, or **VPC**.

For non-composite metrics, the chart divides by your **Group By** dimension.

For more information, see [Dashboard Widgets](https://docs.thousandeyes.com/product-documentation/dashboards/dashboard-widgets).

## 2026-07-07

### Endpoint Local Network Wireless Metrics for OpenTelemetry Data Model v2

ThousandEyes for OpenTelemetry now streams wireless, connection, and signal metrics for Endpoint Experience local network data using Data Model v2. You can monitor active Wi-Fi, wired, and cellular connections with metrics such as signal quality, throughput, link speed, connection score, and cellular signal strength indicators.

The `thousandeyes.source.agent.connection.type` attribute is deprecated. Use `network.connection.type` for all Endpoint Local Network metrics.

For the full list of metrics and attributes, see [Endpoint Experience Local Network](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/data-model/data-model-v2/metrics#endpoint-experience-local-network).

## 2026-07-06

### Mobile Endpoint Agent Android Version 1.8.0

The Mobile Endpoint Agent includes the following enhancements:

* Updated the open source license declarations to reflect the latest libraries used by the agent.
* Added fallback scheduling to improve reliability when exact alarms are unavailable.
* Fixed an issue where HTTP connection timeouts could be incorrectly reported as HTTP 400 errors.
* Updated registration error messages to be clearer when network connectivity is unavailable.

## 2026-07-02

### Endpoint Agent Client Version 2.51.0

The following enhancements have been made to the Endpoint Agent client:

#### All Platforms

* Improved path trace algorithms to increase the success rate for traces that reach the target.
* Fixed an issue where the Endpoint Agent could fail to report the Zscaler VPN profile for endpoints using newer Zscaler clients. The agent now recognizes updated Zscaler gateway log entries, so Zscaler-based dynamic tags and path visualization reflect the connection as expected.
* Fixed an issue that could allow agents on the **NONE** release track to update unexpectedly.

#### Windows

* Fixed a crash caused by an invalid proxy bypass list.
* Fixed an issue that could cause aggressive process relaunches and high CPU usage if the **te-user-agent** process fails to launch.

#### macOS

* Enhanced the Endpoint Agent to support the latest system memory reporting in the upcoming macOS 27 release.

## 2026-07-01

### ThousandEyes MCP Server Works With GenAI-Powered Capabilities Disabled

We've removed agentic capabilities from the ThousandEyes MCP server, so it now functions purely as a standardized, permissioned interface to your ThousandEyes data. The server runs no Cisco or ThousandEyes generative models, does not send your data to a Cisco or ThousandEyes LLM, and does not use your data to train or fine-tune any model.

Because the server no longer performs any generative AI (GenAI), you no longer need to opt-in to ThousandEyes GenAI features to use it. Organizations that have GenAI features disabled, including those that have opted out of GenAI training on their data, can now connect an AI client to the MCP server while keeping those settings in place. Access is governed by the same controls as the ThousandEyes API: API Access permission, API tokens, or the OAuth 2.0 flow, and rate limits.

This gives teams in regulated environments a way to bring AI-assisted network intelligence into their own approved, auditable toolchain, under their own AI governance, without opting into any Cisco-operated generative AI.

{% hint style="info" %}
This reflects the MCP server's capabilities today. Organizations that have opted into GenAI data usage may, in the future, see agentic capabilities surfaced through the MCP server. Organizations that remain opted out will continue to access it as the standardized, non-generative data interface described here.
{% endhint %}

No action is required. For more information see the [ThousandEyes MCP Server](https://docs.thousandeyes.com/product-documentation/integration-guides/thousandeyes-mcp-server) documentation.

### DNS Response Details Now Available for HTTP Server Results

HTTP server test results can now show DNS response details when DNS response data is available. These details provide resolver-level evidence from the agent's DNS phase, including the resolver used, protocol, response status and return code, timing, truncation state, and returned records.

Use these details to distinguish DNS resolution issues from later HTTP, SSL/TLS, network, or application failures. For DNS-phase failures, the **Error Details** side panel can show **DNS Responses**. For successful HTTP server results, the **Response Details** side panel can show a **DNS Response** tab when DNS response data is present.

For more information, see [HTTP Server Tests](https://docs.thousandeyes.com/product-documentation/tests/http-server-tests) and [Using the HTTP Server View](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/viewing-data/using-the-http-server-view).

### Agent API Serial Number Reporting for Cisco Devices

The agent API now includes a serial number field for Cisco devices hosting ThousandEyes Enterprise Agents. This gives API consumers a stable hardware identifier for Enterprise Agents that run on supported Cisco platforms, helping teams correlate agent inventory with device inventory and troubleshoot from API data with less manual lookups.

For more information about agent API changes, see the [ThousandEyes API changelog](https://developer.cisco.com/docs/thousandeyes/api-changelog/).

### ThousandEyes Support & Lifecycle Updates: July 2026

#### Recorder IDE End of Life Reminder

[As previously announced](https://docs.thousandeyes.com/whats-new/changelog#revised-recorder-ide-support-timeline), the Recorder IDE v1.24.0 will reach its Functional End of Life (EOL) date on July 26, 2026.

As of this date, the Recorder IDE will enter an unsupported and unmaintained state. While the Recorder IDE may continue to operate beyond this date, ThousandEyes makes no warranties or guarantees regarding its functionality, compatibility, or security. Customers are strongly encouraged to evaluate and transition to alternative solutions prior to this date.

#### Rocky Linux 9.7 End of Life Reminder

Rocky Linux 9.7 will reach its End of Life date on July 29, 2026. Enterprise Agents must be upgraded to a supported operating system version before then to remain functional.

#### Alpine Linux 3.21 End of Installation Support Reminder

Alpine Linux 3.21 will reach End of Installation Support on August 1, 2026. After this date, ThousandEyes will no longer permit new Enterprise Agent installations on this version of the operating system. Existing agents will continue to function and receive support until the End of Support phase begins.

{% hint style="info" %}
This applies to ThousandEyes Enterprise Agents deployed as Docker containers or using the Cisco Application Hosting Framework (CAF).

ThousandEyes does not support the native installation of ThousandEyes Enterprise Agents on Alpine Linux.
{% endhint %}

For upgrade instructions, see [Upgrading Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents).

#### Amazon Linux 2 End of Support Reminder

[As previously announced](https://docs.thousandeyes.com/whats-new/changelog#amazon-linux-2-end-of-installation-support), Amazon Linux 2 entered the End of Support phase on June 30, 2026. ThousandEyes no longer provides support or guarantees software updates, including bug fixes, for Linux package agents running on Amazon Linux 2.

The End of Life date is August 30, 2026. ThousandEyes Enterprise Agents on Amazon Linux 2 must upgrade to Amazon Linux 2023 or another supported OS before then to remain functional. For upgrade instructions, see the [AWS documentation](https://docs.aws.amazon.com/linux/al2/ug/prepare-for-al2023.html).

### New Cloud Agents

New Cloud Agents have been added in the locations listed below. For a full list of Cloud Agents, see [ThousandEyes Cloud Agent Locations](https://www.thousandeyes.com/product/cloud-agents).

#### Alibaba

* Johor, Malaysia (Alibaba ap-southeast-8)
* Mexico (Alibaba na-south-1)
* Paris, France (Alibaba eu-west-2)

#### AWS Regions

* New Zealand (AWS ap-southeast-6)
* Taipei, Taiwan (AWS ap-east-2)

#### AWS Local Zones

* Honolulu, HI (AWS Local Zone) \[us-west-2-hnl-1a]
* Istanbul, Turkey (AWS Local Zone) \[eu-central-1-ist-1a]

#### AWS Wavelength Zones

* Casablanca, Morocco (Orange - AWS Wavelength) \[eu-west-3-cmn-wlz-1a]
* Dakar, Senegal (Orange - AWS Wavelength) \[eu-west-3-dss-wlz-1a]

#### Azure

* Brussels, Belgium (Azure belgiumcentral)
* Copenhagen, Denmark (Azure denmarkeast)
* Jakarta, Indonesia (Azure indonesiacentral)
* Kuala Lumpur, Malaysia (Azure malaysiawest)
* Santiago, Chile (Azure chilecentral)
* Vienna, Austria (Azure austriaeast)

#### GCP

* Bangkok, Thailand (GCP asia-southeast3)
* Querétaro, Mexico (GCP northamerica-south1)

### ThousandEyes Developer Hub Launches on Cisco DevNet

The new [ThousandEyes Developer Hub](https://developer.cisco.com/thousandeyes/) is now live on Cisco DevNet, giving developers and operations teams a dedicated starting point for building with ThousandEyes APIs, automation tools, telemetry integrations, and workflow examples.

Use the hub to find developer resources such as the API v7 developer reference, getting-started guides, automation tooling, and integration guidance from a single DevNet entry point.

For more information, see [ThousandEyes Developer Hub](https://developer.cisco.com/thousandeyes/).

### Bulk Editing in Test Settings

You can now update the test interval and assigned agents for multiple Network & App Synthetics tests from **Network & App Synthetics > Test Settings**. Select the tests you want to change, then use **Edit > Test Interval** to change how often eligible tests run, or **Edit > Manage Agents** to add or remove agents.

Bulk updates are submitted as jobs, so admins can update large sets of tests without opening each test individually. Before you submit a bulk interval change, the workflow flags tests that do not support the selected interval. Before you submit agent changes, you can review which agents will be added to or removed from each test.

For more information, see [Working with Test Settings](https://docs.thousandeyes.com/product-documentation/tests/working-with-test-settings#updating-multiple-tests).

### Cloud Insights Updates

#### AI Assistant Support for Cloud Insights Events

The Cisco AI Assistant now supports AI-assisted analysis for Cloud Insights inventory events and cloud traffic events (currently in Beta - see [previous announcement](https://docs.thousandeyes.com/whats-new/changelog#cloud-traffic-events-for-aws-now-in-beta)). When events are visible in the **Events** table, select **Summarize Events** to generate a consolidated analysis of all visible events, including an overview, key timestamps, possible causes or configuration changes, potential impacts, and recommendations.

To summarize both inventory events and cloud traffic events, go to **Cloud Insights > Views**. For individual inventory event analysis, go to **Cloud Insights > Inventory**.

After the initial summary, you can ask follow-up questions in the AI panel. For more information, including limitations such as the number of events the summary can handle, see [Events in Cloud Insights](https://docs.thousandeyes.com/product-documentation/cloud-insights/views/events-in-cloud-insights#ai-assisted-event-analysis).

## 2026-06-30

### Console Logs in Transaction Test Views

You can now collect browser and transaction-script console output for transaction tests and review it directly in Transaction test views. This gives you more context for browser runtime errors, JavaScript errors, application messages, script-authored messages, timeouts, and other run-specific issues without leaving **Network & App Synthetics > Views**.

To collect logs, open a transaction test in **Network & App Synthetics > Test Settings**, go to **Configure Test > Transaction Performance and Browser Settings (Optional) > Browser Options**, and turn on **Collect console logs**. You can run **Instant Test** to validate the setting and script behavior before saving the configuration for scheduled runs.

In **Network & App Synthetics > Views**, open the **Console Logs** tab for a transaction test to review log **Severity**, **Time**, and **Content** for the selected round and agent. Use these logs with the **Waterfall** tab, screenshots, markers, **Map** and **Table** tab results, errors, and the **Transaction Time** chart to understand what failed and why.

Console output can include sensitive data. Do not log credentials, tokens, session identifiers, personal data, or other sensitive values in browser, application, or transaction-script console output.

For more information, see [Using the Transaction Test View](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/viewing-data/using-the-transaction-test-view#console-logs-tab).

## 2026-06-26

### ThousandEyes CLI Now Available

The ThousandEyes CLI is now available for automating ThousandEyes from the command line. Built on top of the ThousandEyes API, the CLI lets you manage API-backed workflows from a terminal, shell script, or automation pipeline without building a custom API client.

Use the CLI for workflows such as managing tests and resources, working with templates, and using ThousandEyes data in automation environments.

To get started, see [ThousandEyes CLI](https://developer.cisco.com/docs/thousandeyes/thousandeyes-cli/) in the API Developer Resources and the [ThousandEyes CLI GitHub repository](https://github.com/thousandeyes/thousandeyes-cli/).

## 2026-06-22

We've updated the phone contact information for the ThousandEyes Customer Engineering team. To get support by telephone, note the new numbers:

* **Phone - Main**: +1 919-993-2051
* **Phone - ThousandEyes for Government customers**: +1 877-669-1782

The other methods of contacting ThousandEyes Customer Engineering have not been changed.

## 2026-06-19

### Endpoint Agent Client Version 2.47.3

The following enhancements have been made to the Endpoint Agent client:

#### Windows

* Fixed a rare issue that caused Windows agents to crash during agent startup.

## 2026-06-18

### Cloud Agent Local Problem Status Now Available Through the Agent API

A ThousandEyes Cloud Agent "Local Problem" status indicates an impairment within the agent's own hosting environment and does not represent an issue with the monitored target or service. When a Cloud Agent is experiencing a local problem, the affected test data is automatically excluded from alert calculations to preserve monitoring accuracy until the issue is resolved.

Historically, the "Local Problem" status was only visible in the ThousandEyes user interface and was not accessible through APIs for automated workflows. To support API-driven reporting and integrations, ThousandEyes now exposes Cloud Agent local problem information through the agent API. Customers can use this capability to programmatically identify Cloud Agents impacted by local issues and incorporate this information into their own monitoring, reporting, and operational processes.

For more information, see [List Cloud and Enterprise Agents](https://developer.cisco.com/docs/thousandeyes/v7/list-cloud-agents-with-local-problems/).

## 2026-06-15

### Endpoint Agent Client Updates for Catalyst Access Points

The following Endpoint Agent client fixes are now documented for earlier releases where the agent runs on Catalyst access points.

#### Endpoint Agent Client Version 2.35.0

* Fixed an issue where the Endpoint Agent on Catalyst access points could report a misleading link speed after failed attempts to connect to a Wi-Fi network.
* Fixed an issue where the Endpoint Agent on Catalyst access points could miss some Wi-Fi connection failures when multiple failures occurred in quick succession.

#### Endpoint Agent Client Version 2.40.1

* Downgraded some INIT phase events that the Endpoint Agent on Catalyst access points previously reported as Wi-Fi connection failures.

#### Endpoint Agent Client Version 2.42.0

* Resolved an issue where a reduced path MTU could prevent communication between the Endpoint Agent on Catalyst access points and the ThousandEyes platform.

## 2026-06-11

### Additional Device Data in Endpoint Agent

Endpoint Agent now surfaces more device-level data to help you identify endpoints more precisely, assess device health, and troubleshoot user experience issues with more context.

New device dimensions include **Serial Number**, **NIC model**, **NIC driver version**, and **Battery health**. New metrics include **Battery status** and **Free disk space**.

These additions give you more signals to correlate with network and application performance. You can use them to identify patterns such as low disk space, degrading battery health, or outdated wireless drivers, and make more informed decisions about hardware refreshes or remediation.

This data is available across Endpoint Experience, including **Agent Settings** and **Agent Views**. You can also use it in dashboards, reports, API workflows, and fleet-wide analysis.

For more information, see [Data Collected by Endpoint Agent](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/data-collected-by-endpoint-agent) and [Endpoint Agent Views](https://docs.thousandeyes.com/product-documentation/end-user-monitoring/viewing-data/agent-views).

### AI Assistant Troubleshooting in Endpoint Agent Views

You can now use the AI Assistant directly in **Agent Views** to analyze endpoint data, surface likely contributing factors, and recommend what to investigate next for a single user's experience.

The AI Assistant helps reduce manual correlation across device, connection, network, and application data. This makes Endpoint Agent data more accessible for support teams, helps Tier-1 teams troubleshoot faster, and gives teams more confidence when they investigate user experience issues.

For more information, see [Troubleshooting Using the AI Assistant](https://docs.thousandeyes.com/product-documentation/end-user-monitoring/viewing-data/agent-views#troubleshooting-using-the-ai-assistant).

### Endpoint Agent Tags in ThousandEyes for OpenTelemetry Metrics

Endpoint Agent tags associated with the agents that generate Endpoint Experience test results are now converted into OpenTelemetry attributes. These attributes are included on Endpoint Experience test result metrics and local network metrics, helping you group and filter streamed telemetry by Endpoint Agent tag metadata in your observability platform.

For more information, see [Tags as Attributes](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/data-model/data-model-v2/metrics#tags-as-attributes).

### Updated Auto-Disable Notifications for OpenTelemetry Integrations

ThousandEyes now sends updated warning and disable notifications for failing OpenTelemetry streaming integrations. Auto-disabling and notifications apply to integrations you create directly and to OpenTelemetry integrations managed through cross-product integration flows.

For more information, see [Automatic Disabling of Failing Streaming Integrations](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/automatic-disabling).

### Network Provider Information Now Available for Agents

ThousandEyes Cloud and Enterprise Agents now report network provider information through the agent API, including the network provider name, autonomous system number (ASN), and provider category. This information is derived by the agent's public IP address lookup against the ThousandEyes ASN datasets.

In addition to reporting through the agent API, network provider information is now integrated throughout the ThousandEyes platform to simplify agent selection and management. On the Cloud Agents page, you can quickly locate Cloud Agent locations based on your preferred network providers. This provider metadata also powers the **Provider** grouping within the agent selector, enabling you to easily group and select agents by network provider when configuring tests.

* For API documentation, see [Network ProviderInfo - ThousandEyes API v7 - Cisco DevNet](https://developer.cisco.com/docs/thousandeyes/agents-api-model-networkproviderinfo/).
* For more information about autonomous system data sources, see [Autonomous System (AS) Data Sources](https://docs.thousandeyes.com/product-documentation/tests/bgp-tests#autonomous-system-as-data-sources).

## 2026-06-10

### New Tools for the ThousandEyes MCP Server

The following new tools have been added to the ThousandEyes MCP server:

#### Cloud Insights

* `get_cloud_insights_events_analysis_inputs` — Retrieve Cloud Insights events analysis data for cloud inventory and traffic events, with time ranges and entity filters.
* `list_cloud_insights_inventory` — Retrieve Cloud Insights inventory details or inventory changes for selected cloud resources.
* `resolve_cloud_insights_entity_filters` — Resolve Cloud Insights entity names, types, or aliases to canonical filter IDs for follow-up Cloud Insights queries.
* `get_cloud_insights_metrics` — Retrieve Cloud Insights time series metrics for cloud traffic, resource, event, and transit gateway analysis.

#### Endpoint Monitoring

* `get_endpoint_scheduled_test_results` — Retrieve network results for a scheduled Endpoint Agent test, including latency, packet loss, jitter, and bandwidth. Supports time windows and pagination.
* `list_endpoint_agent_dynamic_tests` — List configured Endpoint Agent dynamic tests, including test name, monitored application, interval, protocol, and enabled state.
* `get_endpoint_network_topologies_probes` — Retrieve Endpoint Agent network topology probe data, including local network path and system metric details when available.

#### Advanced Analysis

* `get_detailed_test_results` — Retrieve detailed page load or web transaction results for a specific test, agent, and round.

#### Dashboard Management

* `list_dashboards` — List dashboard summaries in the current account group.
* `get_dashboard` — Retrieve a dashboard definition, including its configured widgets.
* `get_dashboard_widget_data` — Retrieve the raw data rendered by a specific dashboard widget. Supports time windows and pagination.
* `create_dashboard` — Create a new dashboard, optionally with widgets and privacy settings.
* `update_dashboard` — Update an existing dashboard, including its title, description, privacy setting, global filter, or widgets.
* `delete_dashboard` — Delete a dashboard by ID.

#### Alert Rule Management

* `list_alert_rules` — List alert rules for ThousandEyes synthetics, Endpoint Agents, Connected Devices, Cloud Insights, and Traffic Insights.
* `get_alert_rule` — Retrieve one alert rule, including its expression, severity, notification settings, and violation criteria.
* `create_alert_rule` — Create an alert rule with an expression, alert type, severity, violation window, and optional notification settings.
* `update_alert_rule` — Update an existing alert rule. Include the rule ID and the rule payload fields you want to preserve or change.
* `delete_alert_rule` — Delete an alert rule by ID.

#### Tag Management

* `list_tags` — List key-value tags in an account group, including static assignments where available.
* `get_tag` — Retrieve one tag by ID, including tag metadata and static assignments.
* `create_tag` — Create a static or dynamic key-value tag for one supported object type. Include the access type for writable tags. Dynamic tags are supported only for Endpoint Agents.
* `update_tag` — Update tag metadata such as key, value, description, color, assignment type, or Endpoint Agent dynamic filters.
* `assign_tags` — Assign a static tag to supported objects such as tests, dashboards, agents, Endpoint Agent scheduled tests, and Connected Device tests.
* `unassign_tags` — Remove static tag assignments from supported objects.
* `delete_tag` — Delete a tag by ID.

For more information on these tools, see [ThousandEyes MCP Server](https://docs.thousandeyes.com/product-documentation/integration-guides/thousandeyes-mcp-server).

## 2026-06-09

### Endpoint Agent Client Version 2.47.2

The following enhancements have been made to the Endpoint Agent client:

#### All Platforms

* Fixed an issue where a VPN node incorrectly appeared in Test Views and the segment visualization in Agent Views for Cisco ZTA application tests when VPN and ZTA were both active on the same endpoint.

## 2026-06-01

### Firewall Update Required for ThousandEyes Virtual Appliance (TEVA) and ThousandEyes Physical Appliance (TEPA)

As part of our continued efforts to improve the architecture of our BrowserBot tests, we will be transitioning from using the Podman adapter to a Docker-based adapter.

In early July 2026, we will be adding the `docker-ce` package to our ThousandEyes Virtual Appliance (TEVA) and ThousandEyes Physical Appliance (TEPA) images in preparation for the BrowserBot Docker adapter release planned for mid-July.

As part of this effort, we have now added **download.docker.com** to the [Firewall Configuration for Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/firewall-configuration-for-enterprise-agents) documentation, and all customers should update their firewall configuration accordingly before July 1st, 2026.

If you have any questions, please contact ThousandEyes Support.

### ThousandEyes Support & Lifecycle Updates: June 2026

#### Alpine Linux 3.20 End of Life

[As previously announced](https://docs.thousandeyes.com/whats-new/changelog#alpine-linux-3-20-end-of-life-reminder), Alpine Linux 3.20 has now reached the End of Life phase (as of June 1, 2026). ThousandEyes Enterprise Agents deployed as Docker containers or using the Cisco Application Hosting Framework (CAF) based on Alpine Linux 3.20 will no longer be able to communicate with the ThousandEyes platform, and will self-terminate with an error message.

{% hint style="info" %}
ThousandEyes does not support the native installation of ThousandEyes Enterprise Agents on Alpine Linux.
{% endhint %}

Agents must be upgraded to the latest agent image to remain functional. For more information on upgrading your agent:

* For Docker-based agents, see [Upgrading Docker Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#docker-enterprise-agents).
* For CAF Containers for Cisco Devices, see [Upgrading Cisco Devices](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#cisco-application-hosting).
* For upgrading with the SD-WAN Manager, see [Upgrading Cisco ThousandEyes Enterprise Agent Software](https://www.cisco.com/c/en/us/td/docs/routers/sdwan/configuration/system-interface/ios-xe-17/systems-interfaces-book-xe-sdwan/sdwan-thousandeyes.html#concept_crq_qsz_rqb).

#### Alpine Linux 3.21 End of Installation Support Reminder

Alpine Linux 3.21 will reach End of Installation Support on August 1, 2026. After this date, ThousandEyes will no longer permit new Enterprise Agent installations on this version of the operating system. Existing agents will continue to function and receive support until the End of Support phase begins.

{% hint style="info" %}
This applies to ThousandEyes Enterprise Agents deployed as Docker containers or using the Cisco Application Hosting Framework (CAF).

ThousandEyes does not support the native installation of ThousandEyes Enterprise Agents on Alpine Linux.
{% endhint %}

#### Red Hat Enterprise Linux 9.4 End of Life Reminder

[As previously announced](https://docs.thousandeyes.com/whats-new/changelog#red-hat-enterprise-linux-9-4-end-of-support), Red Hat Enterprise Linux 9.4 will reach End of Life on June 29, 2026. Enterprise Agents must be upgraded to a supported operating system version before then to remain functional.

#### Red Hat Enterprise Linux 9.7 End of Life Reminder

[As previously announced](https://docs.thousandeyes.com/whats-new/changelog#red-hat-enterprise-linux-9-7-end-of-installation-support-and-end-of-support), Red Hat Enterprise Linux 9.7 will reach End of Life on June 29, 2026. Enterprise Agents must be upgraded to a supported operating system version before then to remain functional.

#### Rocky Linux 9.7 End of Installation Support and End of Support

[As previously announced](https://docs.thousandeyes.com/whats-new/changelog#rocky-linux-9-7-end-of-installation-support-and-end-of-support-reminder), Rocky Linux 9.7 has now reached both End of Installation Support and End of Support (as of May 30, 2026). ThousandEyes will no longer permit new agent installations on this version, nor provide support services or guarantee software updates (including bug fixes) for existing agents.

The End of Life date for Rocky Linux 9.7 is July 29, 2026. Enterprise Agents must be upgraded to a supported operating system version before then to remain functional.

#### Amazon Linux 2 End of Support Reminder

[As previously announced](https://docs.thousandeyes.com/whats-new/changelog#amazon-linux-2-end-of-installation-support), Amazon Linux 2 will reach End of Support on June 30, 2026. ThousandEyes will no longer provide support or guarantee software updates, including bug fixes, for Linux package agents running on Amazon Linux 2 after this date.

The End of Life date is August 30, 2026. ThousandEyes Enterprise Agents on Amazon Linux 2 must upgrade to Amazon Linux 2023 or another supported OS before then to remain functional. For upgrade instructions, see the [AWS documentation](https://docs.aws.amazon.com/linux/al2/ug/prepare-for-al2023.html).

#### Recorder IDE End of Life Reminder

[As previously announced](https://docs.thousandeyes.com/whats-new/changelog#revised-recorder-ide-support-timeline), the Recorder IDE v1.24.0 entered the End of Support phase on May 27, 2026.

The Functional End of Life (EOL) date is July 26, 2026. As of this date, the Recorder IDE will enter an unsupported and unmaintained state. While the Recorder IDE may continue to operate beyond this date, ThousandEyes makes no warranties or guarantees regarding its functionality, compatibility, or security. Customers are strongly encouraged to evaluate and transition to alternative solutions prior to this date.

### ThousandEyes Physical and Virtual Appliances Now Run on Ubuntu 24.04 LTS

The base operating system for our ThousandEyes Physical Appliance (TEPA) images for Intel / ASUS NUCs, as well as our ThousandEyes Virtual Appliance (TEVA) images for VMware ESXi, VirtualBox, and Hyper-V, has been switched to Ubuntu 24.04 LTS.

With this change, we've also updated the appliance customization in the **Add Agents** dialog to produce images with an Ubuntu 24.04 LTS base.

This has no impact on existing installations. All new installations with the updated images will have the new base operating system.

For more information on support dates for existing installations, see our [Support Lifecycle](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/enterprise-agent-support-lifecycle) documentation.

### Support for ThousandEyes Physical Appliance Agents on ASUS NUC 15 Devices

We now support installing ThousandEyes Physical Appliance (TEPA) agents on ASUS NUC 15 devices. For more information on installation processes and hardware requirements, see [ThousandEyes Physical Appliance (TEPA) Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-physical-appliance-installation).

## 2026-05-29

### ThousandEyes Endpoint Agent for ChromeOS Is Now Generally Available

The ThousandEyes Endpoint Agent for ChromeOS is now generally available. Following the [previously announced Open Beta](https://docs.thousandeyes.com/whats-new/changelog#introducing-the-thousandeyes-endpoint-agent-for-chromeos-open-beta), this release extends ThousandEyes endpoint visibility to Chromebooks and Chrome Enterprise devices.

With this release, organizations can monitor device, network, and application performance for ChromeOS users who rely on SaaS applications, browser-based workflows, and VDI environments.

ChromeOS support is available with Mobile Endpoint Agent version 1.7.1 and later, available on [Google Play](https://play.google.com/store/apps/details?id=com.thousandeyes.endpointagent\&hl=en).

To get started, see the [ChromeOS deployment guide](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/installing/mepa_chromeos).

### Chromium v148 Common Issues

As part of our ongoing efforts to improve customer transaction tests after the recent Chromium 148 release, we have identified some common issues and known solution paths. You can find the current list here: [Chromium v148 Common Issues](https://docs.thousandeyes.com/product-documentation/browser-synthetics/dual-chromium-option/chromium-148-common-issues).

This list will be updated as new solutions emerge.

{% hint style="warning" %}
Only common issues with an identified solution path are included on this page; not all issues are included.
{% endhint %}

{% hint style="info" %}
Please contact ThousandEyes Support if you find an issue not listed here.
{% endhint %}

## 2026-05-28

### New Features in Provider Intelligence

#### Monitored Providers

In **Internet Insights > Provider Intelligence**, you can now save providers from query results to monitor how their performance changes over time.

When you save a provider for monitoring, Provider Intelligence forms a baseline of the provider's performance by capturing in a snapshot your query parameters, the query date, the provider's overall score at that moment, and the scores for each evaluation metric (latency, loss, jitter, and if applicable, Time to First Byte (TTFB)).

Saved providers then appear in a dedicated monitoring section on the Provider Intelligence console. Each time you return, Provider Intelligence compares the latest results with the saved baseline, showing any changes in overall and metric scores. You can also re-run your original query with one click to view your provider's current performance in greater detail.

Use monitored providers to:

* Track provider performance continuously.
* Detect degradation early.
* Support ISP reviews, SLA discussions, and renegotiations using objective historical performance data.

For more information, see [Monitor Providers](https://docs.thousandeyes.com/product-documentation/internet-insights/provider-intelligence/monitor-providers).

#### Shareable Reports

You can now share saved summary reports in Provider Intelligence by creating a public URL. Anyone you send the link to can view the report, even if they don't have a ThousandEyes account, making it easy to circulate provider recommendations and supporting data with executives, procurement teams, and external consultants.

For more information, see [Generate Reports](https://docs.thousandeyes.com/product-documentation/internet-insights/provider-intelligence/generate-reports).

## 2026-05-26

### Path Visualization View Improvements

The **Network & App Synthetics > Views > Path Visualization** view has received several improvements:

* **Collapsible controls bar** — The Path Visualization controls (Show, Group, Highlight, Select) can now be collapsed to maximize the topology canvas.
* **Selection and highlight persistence** — Selected nodes and paths, along with active highlights, are now persisted in the URL and in saved snapshots. A shared link or snapshot reproduces the exact selection state on the receiving end.
* **Delay and response time aggregation** — In the **Path Visualization display preferences** popover, the **Delay and Response Time stats** can now be set to **Min**, **Average**, or **Max**. The setting applies to both node response time and link delay, so you can choose the aggregate that best matches the symptom you are investigating.
* **Finer link delay thresholds** — The **Link Delay** highlight slider now moves in 5 ms increments for tighter latency thresholds when troubleshooting brief delay spikes.
* **Pills-style filters** — Filter inputs in the controls bar now use a pills UX, making selected values easier to scan and remove.
* **More responsive loading states** — Path Visualization shows clearer loading indicators while the topology is being processed.
* **Pagination behavior** — Pagination in Path Visualization now returns you to the top of the graph, so you don't have to scroll back up after switching pages.

#### Bug Fixes

* User-defined grouping (network, location, and so on) now correctly refreshes the Path Visualization when applied.

For details on Path Visualization controls, see [Path Visualization](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/path-visualization).

## 2026-05-22

### Introducing Autonomous System (AS) Details

You can now search for and view key autonomous system (AS) information in one place on the new **AS Details** page. The page summarizes AS number information, announced prefix counts, prefix announcement trends, and routing state summaries. You can filter the prefix list and drill down to prefix-level details. Alerts apply only to prefixes that are monitored in your account. For prefixes that are not monitored, enable monitoring first if you want alerts for those prefixes.

For more information, see [Using the AS Details Screen](https://docs.thousandeyes.com/product-documentation/tests/bgp-tests/using-the-as-details-screen).

### IPv6 Multi-Address Support for ThousandEyes Physical Appliances and ThousandEyes Virtual Appliances

ThousandEyes Physical Appliances (TEPA) and ThousandEyes Virtual Appliances (TEVA) now support configuring multiple IP address assignments on a single interface. Users can select the specific IP address that is best aligned with their routing, segmentation, or monitoring requirements, improving control and deployment versatility across complex network environments, and providing greater flexibility in how monitoring traffic is sourced.

For more information on how multi-address configuration works, see [Enterprise Agent Interface Selection](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/enterprise-agent-interface-selection#multiple-addresses-on-a-single-interface).

## 2026-05-21

### Distributed Tracing with Dynatrace® Platform

ThousandEyes now supports distributed tracing and service-map visualization for Dynatrace, allowing you to consolidate observability data:

* Correlate end-to-end network and application performance (from ThousandEyes tests) with Dynatrace service maps.
* Leverage alerting and dashboards in ThousandEyes alongside Dynatrace trace data.

For more information, see [Distributed Tracing with Dynatrace® Platform](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-built-integrations/distributed-tracing/distributed-tracing-dynatrace-apm).

### Custom Application Classification in Traffic Insights

Traffic Insights now supports custom application classification. Go to **Traffic Insights > Settings > Custom Applications** to define your own internal or proprietary applications by specifying IP ranges, protocols, and port numbers. You can make traffic that previously appeared as `Unknown` recognized and labeled, providing clearer visibility into critical business applications, improving troubleshooting, and making capacity planning more accurate for each environment.

For more information, see [Naming Custom Applications](https://docs.thousandeyes.com/product-documentation/traffic-insights/traffic-insights-configuration-guide/naming-custom-applications).

### Data Window Selector in Traffic Insights

In **Traffic Insights > Views**, you can now toggle table and Sankey metrics between a 5-minute window and the selected chart time range when filtered by client IP. This update supports averaged reporting over extended periods per client.

For more information, see [Viewing Traffic Insights Data: Data Window Selector](https://docs.thousandeyes.com/product-documentation/traffic-insights/traffic-insights-views-and-settings#data-window-selector).

### Advanced Time Selector In Cloud Insights

**Cloud Insights > Inventory** and **Cloud Insights > Views** now feature an **Advanced** time selector. Set specific start and end times to streamline your analysis of events and traffic volumes.

For more information, see [Cloud Insights Views: Selecting a Time Range](https://docs.thousandeyes.com/product-documentation/cloud-insights/views#selecting-a-time-range).

## 2026-05-20

### Endpoint Agent Client Version 2.43.2

The following enhancements have been made to the Endpoint Agent client:

#### All Platforms

* Fixed an issue where Endpoint Agents did not capture Webex meeting details when using a recent Webex client.

## 2026-05-19

### Revised Recorder IDE Support Timeline

{% hint style="info" %}
This notice supersedes the [December 4, 2025](https://docs.thousandeyes.com/whats-new/changelog#recorder-ide-end-of-life-and-migration-plan) deprecation announcement and provides updated support milestones for the ThousandEyes Recorder IDE.
{% endhint %}

**May 27, 2026**: End of Support (EOS) for v1.24.0.

* ThousandEyes will no longer provide technical support for customers running version 1.24.0 of the Recorder IDE.

{% hint style="info" %}
Customers are strongly encouraged to evaluate and transition to alternative solutions prior to this date to ensure continued support and security.
{% endhint %}

**July 26, 2026**: Functional End of Life (EOL)

* As of this date, the Recorder IDE will enter an unsupported and unmaintained state. While the Recorder IDE may continue to operate beyond this date, ThousandEyes makes no warranties or guarantees regarding its functionality, compatibility, or security.

{% hint style="warning" %}
Continued use of the Recorder IDE after this date is entirely at the customer's own risk. ThousandEyes disclaims all liability for any issues, including security vulnerabilities or integration failures, arising from continued use post-EOL.
{% endhint %}

#### Security Advisory

The Recorder IDE includes an embedded version of Chromium that will no longer receive updates or security patches. Customers are strongly advised to consult with their IT and security teams to assess whether continued use of the Recorder IDE is acceptable within their security policies.

### Tag Validation for Stream Integrations

Tags specified in a stream integration are now validated against the tags that exist in your account group. Creating or updating an integration that references a tag not found in the account will return a bad request error.

Ensure all tags referenced in your integrations exist in your account group before creating or updating a stream. For more information, see [Getting Started with ThousandEyes for OpenTelemetry](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/getting-started).

## 2026-05-11

### Chromium Upgrade for Cloud and Enterprise Agents

We have now completed the upgrade of both Chromium versions available in our Cloud and Enterprise Agents ("default" and "latest") to [version 148](https://developer.chrome.com/release-notes/148) to incorporate the latest features and security enhancements.

For more information about version 148, see the [Chrome Releases Blog](https://chromereleases.googleblog.com/2026/05/stable-channel-update-for-desktop.html). If you have questions, contact ThousandEyes Customer Support.

## 2026-05-07

### OpenTelemetry Attributes for Endpoint Agent Tags

Endpoint Agent labels have been migrated to tags, which changes how they are represented as OpenTelemetry attributes.

Previously, labels included only a name and were represented as `<label name>:<label name>`. Tags include both a key and a value and are now represented as `<tag key>:<tag value>`.

For more information, see [Tags as Attributes for v2 metrics](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/data-model/data-model-v2/metrics#tags-as-attributes).

### Chromium Upgrade for BrowserBot

As part of ThousandEyes' agent lifecycle management, we periodically update the Chromium browser in both our Cloud and Enterprise Agents so that agent software stays up to date with the latest browser technology and remains compliant with customer internal security policies. In any upgrade cycle, there will be two Chromium versions under consideration: "default" and "latest".

In the coming days, we will be upgrading both "default" and "latest" to version 148 to incorporate new features and security enhancements.

Further updates will be provided in the changelog when these upgrades are complete. For more information on why Chromium upgrades are needed, see [Why Chromium Upgrades](https://docs.thousandeyes.com/product-documentation/browser-synthetics/dual-chromium-option/why-chromium-upgrades).

If you have questions, contact ThousandEyes Customer Support.

### Enhanced Autonomous System (AS) Metadata for BGP Monitoring

We have upgraded AS metadata enrichment so BGP views show deeper, more accurate routing data. ThousandEyes now incorporates additional data from BGP.Tools, APNIC, CAIDA, and RIPE NCC. That data is applied across the ThousandEyes platform wherever AS information is relevant, which enables more precise ASN provider identification in **BGP Route Visualization**, the **BGP Updates** table, and all path views.

This update improves your ability to troubleshoot issues with reachability, network paths, and update timelines. It also helps you troubleshoot reachability, network paths, and update timelines with greater precision. For more information on AS metadata sources, see [Autonomous System (AS) Data Sources](https://docs.thousandeyes.com/product-documentation/tests/bgp-tests#autonomous-system-as-data-sources).

### Terraform Provider: Dashboards and Webhooks Configuration

The ThousandEyes Terraform Provider now supports managing dashboards and webhooks as code. This release introduces the following:

* **Dashboards**: Define and manage operational dashboards in code, including Line, Number, and other supported widget types.
* **Custom integrations (webhooks)**: Configure connectors, webhook operations, and assignments to standardize outbound notifications using the same automation workflow as the rest of your infrastructure.

The provider does not create or manage dashboard filters under `/dashboards/filters` in this release. Dashboards can reference existing filter IDs.

### Endpoint Browser Session Alerts: Configuration and Notifications

We updated Endpoint Browser Session alerts to show context that matches each alert type, so you can triage faster and get more from your Real User Tests data.

#### Notifications

* Browser Sessions Application alerts now summarize affected agents instead of always listing visited sites.
* Browser Sessions Agent alerts now summarize affected visited sites.

#### Integrations

If you automate alert notifications through email, webhooks, or other integrations, review your parsers and workflows. Fields and table structures in these messages have changed.

## 2026-05-06

### Endpoint Agent Client Version 2.43.0

The following enhancements have been made to the Endpoint Agent client:

#### All Platforms

* Updated the installation Terms and Conditions to align with Cisco Terms and Conditions. This update does not change any underlying contracts.

#### macOS

* Fixed an issue where Endpoint Agents did not correctly detect GlobalProtect VPN connections. Scheduled test path visualization now shows the VPN node correctly, and VPN server tests running with the local network configuration now report data as expected.

## 2026-05-04

### Temporary Suspension of Cloud Agents in the AWS Middle East Regions Bahrain (ME-SOUTH-1) and UAE (ME-CENTRAL-1)

Due to ongoing infrastructure availability challenges affecting [AWS regions in Bahrain (AWS me-south-1) and the United Arab Emirates (AWS me-central-1)](https://health.aws.amazon.com/health/status), Cisco ThousandEyes is temporarily suspending Cloud Agents in these locations effective 72 hours from the publication of this changelog notice.

If you are currently running tests on these Cloud Agents, please migrate them to a nearby Cloud Agent location prior to the scheduled suspension date. Alternative locations include:

* Muscat, Oman (AWS Local Zone)
* Tel Aviv, Israel (AWS il-central-1)

We will continue to monitor the status of the regional infrastructure and will provide further updates to this changelog as more information becomes available.

## 2026-05-01

### Support for ThousandEyes Physical Appliance Agents on ASUS NUC 14 Devices

We now support installing ThousandEyes Physical Appliance (TEPA) agents on ASUS NUC 14 devices. For more information on installation processes and hardware requirements, see [ThousandEyes Physical Appliance (TEPA) Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-physical-appliance-installation).

### ThousandEyes Lifecycle Reminders

#### Alpine Linux 3.20 End of Life Reminder

[As previously announced](https://docs.thousandeyes.com/whats-new/changelog#alpine-linux-end-of-support-reminder-1), Alpine Linux 3.20 has entered the End of Support phase, and will reach End of Life on June 1, 2026. ThousandEyes Enterprise Agents deployed as Docker containers or using the Cisco Application Hosting Framework (CAF) based on Alpine Linux 3.20 must be upgraded to the latest agent image before then to remain functional.

{% hint style="info" %}
ThousandEyes does not support the native installation of ThousandEyes Enterprise Agents on Alpine Linux.
{% endhint %}

For more information on upgrading your agent:

* For Docker-based agents, see [Upgrading Docker Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#docker-enterprise-agents).
* For CAF Containers for Cisco Devices, see [Upgrading Cisco Devices](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#cisco-application-hosting).
* For upgrading with the SD-WAN Manager, see [Upgrading Cisco ThousandEyes Enterprise Agent Software](https://www.cisco.com/c/en/us/td/docs/routers/sdwan/configuration/system-interface/ios-xe-17/systems-interfaces-book-xe-sdwan/sdwan-thousandeyes.html#concept_crq_qsz_rqb).

#### Red Hat Enterprise Linux 9.4 End of Support

Red Hat Enterprise Linux 9.4 has now entered the End of Support phase (as of April 30, 2026). ThousandEyes will no longer provide Support Services, nor guarantee software updates (including bug fixes) for customers still running Enterprise Agents on Red Hat Enterprise Linux 9.4.

The End of Life date for Red Hat Enterprise Linux 9.4 is June 29, 2026. Enterprise Agents must be upgraded to a supported operating system version before then to remain functional.

#### Red Hat Enterprise Linux 9.7 End of Installation Support and End of Support

Red Hat Enterprise Linux 9.7 has now entered both the End of Installation Support and End of Support phases (as of April 30, 2026). ThousandEyes will no longer permit new agent installations on this version, nor provide Support Services or guarantee software updates (including bug fixes) for existing agents.

The End of Life date for Red Hat Enterprise Linux 9.7 is June 29, 2026. Enterprise Agents must be upgraded to a supported operating system version before then to remain functional.

#### Rocky Linux 9.7 End of Installation Support and End of Support Reminder

Rocky Linux 9.7 will reach End of Installation Support and End of Support on May 30, 2026. Following this, it will reach End of Life on July 29, 2026. We recommend planning your operating system upgrades in advance of these dates to ensure continuous service.

#### Amazon Linux 2 End of Support Reminder

[As previously announced](https://docs.thousandeyes.com/whats-new/changelog#amazon-linux-2-end-of-installation-support), Amazon Linux 2 will reach End of Support on June 30, 2026. ThousandEyes will no longer provide support or guarantee software updates, including bug fixes, for Linux package agents running on Amazon Linux 2 after this date.

The End of Life date is August 30, 2026. ThousandEyes Enterprise Agents on Amazon Linux 2 must upgrade to Amazon Linux 2023 or another supported OS before then to remain functional. For upgrade instructions, see the [AWS documentation](https://docs.aws.amazon.com/linux/al2/ug/prepare-for-al2023.html).

#### ThousandEyes API v6 End of Life Reminder

[As previously announced](https://docs.thousandeyes.com/whats-new/changelog#thousandeyes-api-v6-end-of-life-reminder-1), ThousandEyes API v6 and all earlier API versions will be permanently retired on May 27, 2026. After that date, these API versions will no longer be supported or available. Any integration or workflow that still relies on API v6 or earlier will stop working.

If you still use unsupported API versions, migrate to API v7 now to avoid service disruptions. For step-by-step guidance, see the [API v7 Migration Guide](https://developer.cisco.com/docs/thousandeyes/migration-guide-overview/).

### New Cloud Agents

New Cloud Agents have been added in the locations listed below. For a full list of Cloud Agents, see [ThousandEyes Cloud Agent Locations](https://www.thousandeyes.com/product/cloud-agents).

* St. Louis, MO, USA (IPv6)

## 2026-04-30

### Credential Vault Integration with CyberArk® Secrets Manager, Self-Hosted

The Credential Vault Integration is generally available starting today. Enterprise Agents can now retrieve credentials from a customer-managed CyberArk® Secrets Manager, Self-Hosted vault at test runtime, removing the need to store secrets in the ThousandEyes platform. When a credential rotates in CyberArk, the change takes effect across every ThousandEyes test that uses it, with no manual updates required.

**What You Can Do with Credential Vault**

* **Retrieve credentials in real time.** Secrets are fetched at test runtime, held in memory only for the duration of the test, and never stored, cached, or logged in ThousandEyes.
* **Use across authenticated test types.** Credential Vault is supported for HTTP Server, Page Load, Transaction, and API tests on Enterprise Agents.
* **Manage agent-level access.** A new **Credential Vault Accessor** module on the Enterprise Agent handles all vault communication. You can enable or disable the module per agent from **Manage > Agent Settings**.
* **Configure via UI or API.** Set up the integration and assign vault credentials to tests through the test settings UI, the Step Builder for API tests, the Transaction test scripting interface, or the v7 API.

**Supported Vault and Agent Types**

* **Vault:** CyberArk® Secrets Manager, Self-Hosted (formerly Conjur Enterprise).
* **Enterprise Agents:** Docker, Linux Package Agents, ThousandEyes Virtual Appliance (TEVA), and ThousandEyes Physical Appliance (TEPA).

For more information, see [Integrating with CyberArk® Secrets Manager, Self-Hosted](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-built-integrations/cyberark).

## 2026-04-28

### Event Detection Alerts for Endpoint Experience

You can now configure Event Detection alert rules for Endpoint Experience events. See [Event Detection Alerts](https://docs.thousandeyes.com/product-documentation/event-detection#event-alerts-and-notifications) and [Event Detection Alert Metrics](https://docs.thousandeyes.com/product-documentation/alerts/creating-and-editing-alert-rules/alert-metrics-reference#event-detection-alerts) for more details.

### Updated Connected Devices Navigation

**Connected Devices** navigation now has clearer labels and a flatter structure. The top-level menu includes **Dashboards**, **Analytics**, **ConstantCare**, **Maps**, **Reports**, **Data Export**, and **Settings**.

![Small image in HTML](/files/3pgX9mz2UjxBdRQkSfyc)

**Settings** includes **Agent Settings**, **Test Settings**, **Test Manager (legacy)**, and **Your APIs**. Legacy labels are also updated: **Chart Views** is now **Dashboards**, **Mapping** is now **Maps**, and **Management Suite** is now **Agent Settings**. Existing dashboard and map links continue to work.

![Small image in HTML](/files/LSqabWtO66cFHa7ccoar)

### Customize Dashboards with Grid Layout

You can now arrange dashboard widgets on a flexible 12-column grid, whether for NOC monitoring, executive summaries, or triage workflows. You get denser dashboards where every widget is sized to fit its data and arranged to match your team's priorities. Grid layout is the new default for any dashboard you create, edit, or duplicate, replacing the previous vertical-only stack.

**Key Features**

* **Resize widgets directly** - use the corner and edge handles to size widgets to the data they contain.
* **Drag to rearrange** - grab the handle in the center of the widget header and drop the widget anywhere on the grid. The grid auto-arranges to avoid gaps and overlaps.
* **Responsive on smaller screens**- the grid automatically collapses to fewer columns (and to a single column on phones), without changing your saved layout.
* **Faster long dashboards** -  widgets defer their data fetch until scrolled into view, and stay cached as you scroll.
* **Full-size view**- open any widget in full-size view using the widget controls or by pressing `v`.

Vertical layout is still available when you create or edit a dashboard. Existing vertical dashboards remain unchanged unless you manually switch them to grid layout.

For details, see [Dashboard Grid Layout](https://docs.thousandeyes.com/product-documentation/dashboards/customizing-your-dashboard#dashboard-grid-layout)

### Introducing the ThousandEyes Endpoint Agent for ChromeOS (Open Beta)

We are pleased to introduce the ThousandEyes Endpoint Agent for ChromeOS (Open Beta). This release extends visibility to Chromebooks, which are seeing accelerated adoption across education, financial services, and enterprise environments. Support for Chromebooks and Chrome Enterprise devices begins with Mobile Endpoint Agent version 1.7, available on [Google Play](https://play.google.com/store/apps/details?id=com.thousandeyes.endpointagent\&hl=en).

This Open Beta provides end-to-end visibility into ChromeOS device performance and network health. This helps ensure reliable access to SaaS applications, browser-based workflows, and VDI environments.

As organizations adopt Chromebooks as cost-effective thin clients to replace traditional VDI endpoints, visibility is essential. ThousandEyes provides the insights you need to identify and resolve connectivity issues with VDI platforms, SaaS applications, and conferencing systems, helping to maintain productivity.

**Key Features**

* Scheduled tests: Run ICMP and HTTP tests in the background.
* Comprehensive monitoring: Includes Path Visualization, dashboards, alerts, the MCP connector, and Device Health & Experience Score.
* Simplified deployment: Deploy using enterprise management tools, such as the Google Admin console.

#### Current Limitation

Application auto-launch: This is not currently supported on ChromeOS. Users must initiate the application manually once. Google is expected to address this limitation as part of their new operating system, which will merge [Android and ChromeOS into a unified platform](https://chromeos.dev/en/posts/building-a-faster-smarter-chromebook-experience-with-the-best-of-google).

To get started, see our [Deployment Guide](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/installing/mepa_chromeos). For support, contact <mepa@cisco.com>.

## 2026-04-27

### Provider Intelligence Now Available in Internet Insights

With Provider Intelligence, you can evaluate and compare internet service providers and peering partners side-by-side using months of pre-collected performance data, without installing agents or configuring tests.

* **Instant Data:** Generate provider comparisons in seconds, not months.
* **Deep Analysis:** Compare providers across multiple time periods, 20+ metrics, and hundreds of destinations and user locations.
* **Saveable Reports:** Keep a record of each search query and tag your preferred providers.

Provider Intelligence is included free with your Internet Insights subscription.

Go to **Internet Insights > Provider Intelligence** to run your first comparison. For more information, see [Provider Intelligence](https://docs.thousandeyes.com/product-documentation/internet-insights/provider-intelligence).

### Customize Widgets with Dynamic Variables

You can now use dynamic variables in widget titles and descriptions to automatically display the configured metric, measure, and group-by settings. This update eliminates the need to manually rename widgets when you change configurations, making it easier to maintain dashboards at scale.

#### Supported variables

* `{metric}`: Displays the selected metric name (for example, Response Time or Throughput).
* `{measure}`: Displays the aggregation type (for example, Mean or 95th Percentile).
* `{groupBy}`: Displays the group-by dimension in plural form (for example, Agents or Tests).
* `{filterNames}`: Displays the names of active filters applied to the widget.
* `{filters}`: Displays the configured filters with their selected values (for example, Agent: SF, NYC; Test: Login).

#### Example

If you set a title to `{metric}` - `{measure}` by `{groupBy}`, the widget automatically displays "Response Time - Mean by Agents."

The title updates automatically whenever you change the widget configuration.

For details, see [Customize Widgets with Dynamic Variables](https://docs.thousandeyes.com/product-documentation/dashboards/customizing-your-dashboard#customize-widgets-with-dynamic-variables).

### Endpoint Experience Now Supports Anonymization for Endpoint PII Data

ThousandEyes now uses anonymization for Endpoint personally identifiable information (PII) protected by specific permissions, enabling users to troubleshoot data without requiring access to sensitive fields. Because this process consistently maps original values to the same anonymized output, organizations can extend Endpoint visibility and support cross-team collaboration while maintaining compliance with privacy regulations such as GDPR.

This applies to the following Endpoint PII permissions:

* View endpoint experience data that identifies location (New permission)
* View endpoint experience data that identifies Endpoint Agents
* View endpoint experience data that identifies network
* View endpoint experience data that identifies users
* View endpoint experience data that identifies visited pages

The new location permission is enabled by default in existing built-in roles to preserve previous behavior. However, when creating new roles, you must now configure this permission explicitly as with the rest of PII-related roles.

For more information, see [Built-in Roles and Permissions](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control/built-in-roles-and-permissions) and [Managing Endpoint PII Information](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents#managing-endpoint-pii-information).

{% hint style="info" %}
To ensure role changes take effect, the user must sign out and sign back in to the application. This action refreshes the user's session and ensures that the updated permissions are applied correctly.
{% endhint %}

## 2026-04-22

### Endpoint Agent Client Version 2.42.0

The following enhancements have been made to the Endpoint Agent client:

#### Catalyst Access Points

* Resolved an issue where reduced path MTU settings prevented the Endpoint Agent on Catalyst access points from communicating with the ThousandEyes platform.

#### macOS

* Resolved an issue where the Endpoint Agent failed to detect GlobalProtect VPN connections, which caused the VPN node to be missing from PathViz.

## 2026-04-16

### New Error Message When BrowserBot Is Unresponsive

Starting with ThousandEyes agent version 1.234.0, the Enterprise Agent generates an error message ("Browserbot is unresponsive") when the execution of a BrowserBot test or the processing of the results encountered a failure, for intervals that previously would have had no data at the web layer.

If you see this message, and it does not correlate with other actions that would prevent the test from running (like a service modification or image update), reach out to ThousandEyes Support for further troubleshooting.

## 2026-04-15

### Mobile Endpoint Agent Android Version 1.7.0

The following enhancements have been made to the Mobile Endpoint Agent:

* Resolved an issue where the visualization incorrectly displayed the ARC bridge gateway (0.0.0.0 or 100.115.92.21) instead of the actual LAN gateway.
* Fixed an issue that caused the application to crash when attempting to fetch location data.
* Improved error logging by including OS-provided error codes, enabling more efficient troubleshooting of connection issues.
* Updated the error reporting mechanism to include the target IP address in additional error states, providing better diagnostic context.
* Fixed an application crash that occurred when the Alarm service attempted to release system resources.

## 2026-04-10

### ThousandEyes Lifecycle Reminders

#### Alpine Linux End of Support

Alpine Linux 3.20 has now entered the End of Support phase. ThousandEyes will no longer provide Support Services, nor guarantee software updates (including bug fixes) for customers still running Enterprise Agents on Alpine Linux 3.20.

The End of Life date for Alpine 3.20 is June 1st, 2026. ThousandEyes Enterprise Agents deployed as Docker containers or using the Cisco Application Hosting Framework (CAF) based on Alpine Linux 3.20 must be upgraded to the latest Agent image before then to remain functional.

{% hint style="info" %}
ThousandEyes does not support the native installation of ThousandEyes Enterprise Agents on Alpine Linux.
{% endhint %}

For more information on upgrading your agent:

* For Docker-based agents, see [Upgrading Docker Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#docker-enterprise-agents).
* For CAF Containers for Cisco Devices, see [Upgrading Cisco Devices](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#cisco-application-hosting).
* For upgrading with the SD-WAN Manager, see [Upgrading Cisco ThousandEyes Enterprise Agent Software](https://www.cisco.com/c/en/us/td/docs/routers/sdwan/configuration/system-interface/ios-xe-17/systems-interfaces-book-xe-sdwan/sdwan-thousandeyes.html#concept_crq_qsz_rqb).

#### Recorder IDE End of Life Reminder

[As previously announced](https://docs.thousandeyes.com/whats-new/changelog#recorder-ide-end-of-installation-support-and-deprecation-timeline), the Recorder IDE will reach End of Life on May 27th, 2026. We strongly recommend you migrate your test creation process to the Google Chrome Recorder or another SaaS-based transaction test creation option before the End of Life date.

* **Watch:** [Video Walkthrough: Importing from Google Chrome Recorder](https://app.vidcast.io/share/09e72e59-f22b-47ea-af08-e3f59aa24f63)

#### Amazon Linux 2 End of Installation Support

Amazon Linux 2 has now entered the [End of Installation Support](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/enterprise-agent-support-lifecycle#amazon-linux) phase, and will reach End of Support on June 30, 2026. ThousandEyes will no longer provide support or guarantee software updates, including bug fixes, for Linux package agents running on Amazon Linux 2 after this date.

The End of Life date is August 30, 2026. ThousandEyes Enterprise Agents on Amazon Linux 2 must upgrade to Amazon Linux 2023 or another supported OS before then to remain functional.

For upgrade instructions, see the [AWS documentation](https://docs.aws.amazon.com/linux/al2/ug/prepare-for-al2023.html).

## 2026-04-09

### ThousandEyes Virtual Appliance (TEVA) and ThousandEyes Physical Appliance (TEPA) Agent Web UI Security Enhancement

From ThousandEyes appliance version 0.262.0 and onwards, we have implemented two security enhancements to the ThousandEyes Virtual Appliance (TEVA) and ThousandEyes Physical Appliance (TEPA) agent web interfaces:

* Users cannot make configuration changes while the administrator password is the default value.
* Password change and reset events will be logged in the system log.

For installation and initial configuration, see:

* [ThousandEyes Virtual Appliance Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-virtual-appliance-installation)
* [ThousandEyes Physical Appliance (TEPA) Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-physical-appliance-installation#configuring-the-enterprise-agent).

## 2026-04-07

### ThousandEyes Virtual Appliance (TEVA) and ThousandEyes Physical Appliance (TEPA) docker-ce Package Update

ThousandEyes recently made an update to the ThousandEyes Virtual Appliance (TEVA) and ThousandEyes Physical Appliance (TEPA) images to add the `docker-ce` package in preparation for an upcoming BrowserBot Docker adapter release. The `docker-ce` default subnet range (`172.17.0.1`) overlapped with some customer proxy environments that were also using `172.17.0.1`, and messages appeared in the agent log files noting TEVA and TEPA agents reaching out to `download.docker.com`. ThousandEyes has rolled back the change until we could update the BrowserBot subnet ranges.

During the rollback, some files were not fully removed, which resulted in the TEVA and TEPA agents continuing to reach out to `download.docker.com`, even after the rollback was complete and the new subnet ranges were implemented \[1]. Additionally, the firewall configuration documentation \[2] was updated to include `download.docker.com` in advance of the upcoming change.

We are in the process of removing the files that caused the TEVA and TEPA agents to reach out to `download.docker.com` and have removed the reference from the firewall documentation. We will update this changelog 30 days prior to reintroducing the changes to the agent image.

* \[1] [Updates to BrowserBot Subnet IP Ranges](https://docs.thousandeyes.com/whats-new/changelog#updates-to-browserbot-subnet-ip-ranges)
* \[2] [Firewall Configuration for Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/firewall-configuration-for-enterprise-agents)

### Distributed Tracing Support for Page Load and Transaction Tests

You can now configure distributed tracing for both page load and transaction tests, in addition to HTTP server and API tests. For more information, see [Distributed Tracing](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-built-integrations/distributed-tracing).

## 2026-04-01

### Endpoint Agent Client Version 2.40.1

The following enhancements have been made to the Endpoint Agent client:

#### All Platforms

* Optimized resource usage on target devices by sending RST packets for some unacknowledged SYN requests during network tests.

#### Windows

* The updater now ensures that the digital signature of the MSI installer is verified against the official ThousandEyes certificate for authenticity and integrity of the installation package.

#### macOS

* Fixed an issue that prevented the Endpoint Agent from detecting VPN connections when using Zscaler client version 4.4 or later.
* Fixed an issue that caused the Endpoint Agent to report incorrect network change events.

### New Tools for the ThousandEyes MCP Server

The following new tools have been added to the ThousandEyes MCP server:

* `get_service_map`
* `list_cloud_enterprise_agents`
* `get_templates`
* `deploy_template`
* `create_synthetic_test`
* `update_synthetic_test`
* `delete_synthetic_test`
* `get_instant_test_metrics`

For more information on these tools, see [ThousandEyes MCP Server](https://docs.thousandeyes.com/product-documentation/integration-guides/thousandeyes-mcp-server).

## 2026-03-31

### Labels Replaced by Tags

As [previously announced](https://docs.thousandeyes.com/whats-new/changelog#advance-notice-on-labels-to-tags-ui-changes), tags are generally available starting today and will be enabled for all customer organizations over the next two weeks. Labels have been replaced by tags, a more flexible, centralized metadata model that supports `key:value` pairs and a single workspace to manage tags across your account.

#### What You Can Do with Tags

* **Structured metadata** — Use `key:value` pairs (for example, `env:prod` or `region:us-east`) for richer context than flat label names allowed.
* **One place to manage tags** — Go to [**Manage > Tags**](https://app.thousandeyes.com/manage/tags/) to create, edit, assign, and delete tags across tests, agents, and dashboards.
* **Filter and group everywhere** — Use tags in test views, dashboard widgets, dashboard global filters, alert rules, and agent settings.
* **Create tags inline** — When configuring a test, agent, or dashboard, type in the tag field to create and assign a tag on the fly.

#### Automatic Migration from Labels

No action is required. Your existing labels were converted to tags automatically. Each label is now a tag whose **key** is the former label name and whose **value** is empty. For example, a label named `subnet-10` is now a tag with key `subnet-10` and no value.

You can add or edit values from [**Manage > Tags**](https://app.thousandeyes.com/manage/tags/) at any time.

#### API

Tags are managed with the [Tags API (v7)](https://developer.cisco.com/docs/thousandeyes/list-tags/).

**Note:** The test details endpoint (`GET /v7/tests/{testId}`) does not return tag assignments. To retrieve tags for a specific test or agent, use `GET /v7/tags?expand=assignments` and filter by assignment type and the relevant object ID.

#### Known Limitations

* **OpenTelemetry streaming** — Tag keys that contain spaces or characters that do not comply with [OpenTelemetry naming conventions](https://opentelemetry.io/docs/specs/semconv/general/naming/) are excluded from streamed telemetry. For streams, limit tag keys to letters, digits, underscores, hyphens, and dots. See [Tags as attributes](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/data-model/data-model-v2/metrics#tags-as-attributes) for details.
* **Test templates** — Some user-created test templates might still show the word `label` in the JSON editor. Tags appear correctly in the Tags UI, and the underlying test behavior is unchanged. A full update to the template JSON editor is planned before May 2026.

For more information, see [Get Started with Tags](https://docs.thousandeyes.com/product-documentation/tags/tags-overview) and [Work with Key-Value Tags](https://docs.thousandeyes.com/product-documentation/tags/working-with-tags).

### Kerberos Authentication for Proxy Configuration

Kerberos is now supported for authentication in proxy environments. When an Enterprise Agent with an assigned Kerberos profile connects to a proxy, it will use Kerberos to authenticate, enabling more accurate testing of enterprise environments that rely on Kerberos-authenticated proxies.

To configure Kerberos authentication in proxy environments:

1. Configure the Kerberos Profile, and assign it to the Enterprise Agent.
2. Configure the proxy profile to use Kerberos authentication.
3. Configure an Enterprise Agent to use the proxy server.

For more information, see:

* [Kerberos Settings](https://docs.thousandeyes.com/product-documentation/global-vantage-points/working-with-agent-settings#kerberos-settings)
* [Configure an Enterprise Agent to Use a Proxy Server](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/proxy/configuring-an-enterprise-agent-to-use-a-proxy-server)

## 2026-03-27

### Cloud Insights Updates

#### Inventory Table Enhancements

The inventory table at **Cloud Insights > Inventory** has several new features to improve inventory analysis, helping you tailor your view and find relevant resources faster:

* **Resource state column** — A new column that reflects status changes for cloud resources.
* **User-selectable columns** — Users can select which columns to display and their order, optimizing the inventory table layout and content.
* **Expanded search function** — Search now allows you to find any visible field in the inventory table.

For more information about these features, see [Cloud Insights: Views](https://docs.thousandeyes.com/product-documentation/cloud-insights/views#inventory-screen)

#### New Inventory Events Configuration Functionality

New inventory events configuration in **Cloud Insights > Settings** gives you control over which inventory events are visible across the Cloud Insights UI landscape. This helps you reduce noise from high-volume automated changes such as autoscaling, so you can focus on the events that matter most.

See [Cloud Insights: Settings](https://docs.thousandeyes.com/product-documentation/cloud-insights/settings#events-configuration) for more information.

#### Cloud Traffic Events for AWS Now in Beta

If you have AWS flow logs configured for Cloud Insights, you can now opt in to see cloud traffic events in **Cloud Insights > Views**. Traffic events, shown in pink along the events timeline, automatically detect and flag anomalous traffic patterns, enabling you to quickly identify unexpected spikes, drops, or blocked traffic without manually sifting through flow log data. Detected patterns include:

* Abnormal accepted and rejected throughput.
* Abnormal accepted and rejected connections.

This feature is in Beta and will be extended over time. Contact your Cisco ThousandEyes solution engineer for more detail.

**Note:** Cloud traffic events are not yet supported for alerting, dashboards, or Azure.

## 2026-03-26

### Advanced Chrome Flags & Chrome Policy Configuration for Page Load and Transaction Tests

You can now add advanced Chrome flags to, and adjust the Chrome policy configuration for, page load and transaction tests from within the ThousandEyes web application:

**Feature highlights**

* **Advanced Chrome Flags**: Command-line-style flags for experiments, behavior changes, disabling features, or environment simulation. (E.g. can override Browser handling of HTTP 2.0 or QUIC defaults for that test only).
* **Chrome policy**: JSON key/value pairs for policy enforcement, security restrictions, and feature controls (E.g. policies for cookies, pop-ups or media autoplay - see Google's policy docs for the full list).
* **Faster, more flexible browser-test troubleshooting**: before, engineering would have to manually adjust the flag or setting and redeploy BrowserBot. Now, these capabilities are available to the end user at the test level in settings.

### ThousandEyes API v6 End-of-Life Reminder

On May 27, 2026, ThousandEyes API v6 and all earlier API versions will be permanently retired. After that date, these API versions will no longer be supported or available. Any integration or workflow that still relies on API v6 or earlier will stop working.

If you still use unsupported API versions, migrate to API v7 now to avoid service disruptions.

#### Impact

* API v6 and all earlier versions will be decommissioned on May 27, 2026. Requests to deprecated endpoints will fail.
* Only Terraform Provider v3 is built on API v7. If you use Terraform Provider v2 or earlier, your automation will break after end of life. Upgrade to [Terraform Provider v3](https://registry.terraform.io/providers/thousandeyes/thousandeyes/latest/docs) as part of your migration.
* API v7 is the only version supported by current tools and SDKs, including the ThousandEyes Java SDK and Python SDK.

#### What You Need to Do

* Complete your migration to API v7 before May 27, 2026.
* Use only [documented API v7 operations](https://developer.cisco.com/docs/thousandeyes/). Do not rely on undocumented or preview operations that may appear to work after a v6-to-v7 substitution. Those operations are not guaranteed to remain stable or supported.

For step-by-step guidance, see the [API v7 Migration Guide](https://developer.cisco.com/docs/thousandeyes/migration-guide-overview/). For more information, see [ThousandEyes API v7 documentation](https://developer.cisco.com/docs/thousandeyes/) or contact our team.

We strongly recommend that every customer still on API v6 or earlier migrate to API v7 immediately.

### Cloud Agent Decommission Notice Reminder

As part of our ongoing efforts to optimize resources and expand coverage in high-impact business areas, we will be decommissioning the following ThousandEyes Cloud Agent locations on the dates listed below:

**March 31st, 2026**

* Accra, Ghana
* Accra, Ghana (IPv6)
* Surabaya, Indonesia
* Surabaya, Indonesia (IPv6)
* Yogyakarta, Indonesia
* Yogyakarta, Indonesia (IPv6)

**April 10th, 2026**

* Chicago, IL, USA

#### Action Required

If you are currently running tests on these Cloud Agents, you will need to migrate them to a nearby Cloud Agent location as soon as possible. If no action is taken by the date listed, the affected Cloud Agents will be removed from your tests. Any tests relying exclusively on these Cloud Agents will be automatically disabled.

To update your tests:

1. Navigate to your test configuration settings in the ThousandEyes platform.
2. Remove the decommissioned agents from your test target list.
3. Add the recommended alternative Cloud Agent locations to ensure continued coverage.

**Nearest available Chicago-based Cloud Agent locations:**

* Chicago, IL, USA (Webex Calling)
* Dallas, TX, USA (Webex Calling)
* Dallas, TX, USA (Webex Meetings)
* Montreal, Canada (Webex Meetings)
* New York, NY, USA (Webex Meetings)
* San Jose, CA, USA (Webex Meetings)
* Toronto, Canada (Webex Calling)
* Toronto, Canada (Webex Meetings)
* Vancouver, Canada (Webex Calling)

**Nearest available Jakarta-based Cloud Agent locations:**

* Jakarta, Indonesia
* Jakarta, Indonesia (Alibaba ap-southeast-5)
* Jakarta, Indonesia (AWS ap-southeast-3)
* Jakarta, Indonesia (Biznet)
* Jakarta, Indonesia (GCP asia-southeast2)
* Jakarta, Indonesia (PT Telkom)
* Jakarta, Indonesia (IPv6)
* Jakarta, Indonesia (Biznet)
* Jakarta, Indonesia (PT Telkom) (IPv6)

**Nearest available Nigeria-based Cloud Agent locations:**

* Lagos, Nigeria
* Lagos, Nigeria (AWS Local Zone)
* Lagos, Nigeria (IPv6)

If you have questions or need assistance migrating your monitoring setup, contact ThousandEyes Support.

## 2026-03-25

### Announcing the General Availability of Cisco ThousandEyes for Government

Cisco ThousandEyes for Government is a [FedRAMP® Moderate–authorized](https://www.fedramp.gov/marketplace/products/FR2523656707/) deployment for U.S. public sector organizations that need digital experience assurance and network visibility under controlled, compliance-oriented operating conditions. It is aimed at federal, state, and local agencies, contractors, and educational institutions that handle Controlled Unclassified Information (CUI) and other regulated workloads.

The authorized platform runs in AWS GovCloud (US) with U.S.-hosted data, FIPS 140–2 validated encryption, and access controls that include multi-factor authentication (MFA) and Okta for Government® single sign-on (SSO) for authorized users. You can use ThousandEyes Enterprise Agents, Endpoint Agents, Cloud Agents, and dedicated monitors where applicable to collect telemetry and troubleshoot user, application, network, and cloud-dependent paths (for example DNS, BGP, and SaaS dependencies), consistent with the authorized scope.

For more information, see [ThousandEyes for Government: FedRAMP Moderate](https://docs.thousandeyes.com/product-documentation/thousandeyes-for-government), the [FedRAMP Marketplace](https://www.fedramp.gov/marketplace/products/FR2523656707/), or contact your Cisco or partner representative.

{% hint style="warning" %}
Customers may deploy tests for Cloud Agents under a ThousandEyes for Government subscription, but any such deployment would be outside of the ThousandEyes’ FedRAMP-authorized boundary. ThousandEyes' obligations under the Authorization to Operate and the FedRAMP baseline requirements would not apply to the Cloud Agents or the data transmitted to or from the Cloud Agents. Customers are solely responsible for accessing and utilizing the Cloud Agent in accordance with their security policies and applicable FedRAMP and federal compliance requirements.
{% endhint %}

## 2026-03-24

### Reduced Auto-Disable Time for Failing OpenTelemetry Integrations

We have reduced the time it takes to automatically disable failing ThousandEyes for OpenTelemetry integrations. This helps limit repeated failed export attempts. For more information, see [Automatic Disabling of Failing Streaming Integrations](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/automatic-disabling).

### Updated Retry Behavior for OpenTelemetry Integrations

We updated the exporter configuration used by OpenTelemetry integrations to improve backpressure handling and reduce prolonged retry attempts.

These changes apply to OTLP gRPC, OTLP HTTP, and Splunk HEC exporter configurations. For details, see [OpenTelemetry Collector Configuration](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/otel-collector-config).

## 2026-03-20

### Alpine Linux End of Support Reminder

[As previously announced](https://docs.thousandeyes.com/whats-new/changelog#alpine-linux-end-of-support-reminder-1), Alpine Linux 3.20 will enter the End of Support phase on April 1st, 2026. ThousandEyes will no longer provide Support Services, nor guarantee software updates (including bug fixes) for customers still running Enterprise Agents on Alpine Linux 3.20 after this date.

Following this, it will enter the End of Life phase on June 1st, 2026. ThousandEyes Enterprise Agents deployed as Docker containers or using the Cisco Application Hosting Framework (CAF) based on Alpine Linux 3.20 must be upgraded to the latest Agent image before then to remain functional.

{% hint style="info" %}
ThousandEyes does not support the native installation of ThousandEyes Enterprise Agents on Alpine Linux.
{% endhint %}

For more information on upgrading your agent:

* For Docker-based agents, see [Upgrading Docker Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#docker-enterprise-agents).
* For CAF Containers for Cisco Devices, see [Upgrading Cisco Devices](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#cisco-application-hosting).
* For upgrading with the SD-WAN Manager, see [Upgrading Cisco ThousandEyes Enterprise Agent Software](https://www.cisco.com/c/en/us/td/docs/routers/sdwan/configuration/system-interface/ios-xe-17/systems-interfaces-book-xe-sdwan/sdwan-thousandeyes.html#concept_crq_qsz_rqb).

## 2026-03-19

### OpenTelemetry Metrics: Marker Attribute for Web Transaction Tests

We updated the OpenTelemetry metrics for [Network & App Synthetics Tests](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/data-model/data-model-v2/metrics#network-and-app-synthetics-tests) to include the `marker` datapoint attribute for Web Transaction tests.

The `marker` attribute identifies a step in the user journey or business transaction (for example, `Login`).

## 2026-03-17

### Redesigned Cloud Agent Settings Page

We are pleased to announce a redesigned interface for the [Cloud Agent settings page](https://app.thousandeyes.com/network-app-synthetics/agent-settings/cloud/?section=agents), aimed at improving your workflow and overall user experience.

* Enhanced Agent Management: Added a dedicated **Labels** column, support for customizable column sizing, and pagination to improve navigation.
* Advanced Search Functionality: You can now filter and search for agents by agent name, provider name, region, or labels.
* Streamlined Assignments: Test and tag assignments can now be managed directly through a new side panel, reducing the need to navigate away from your current view.

For more information, see [Working with Agent Settings](https://docs.thousandeyes.com/product-documentation/global-vantage-points/working-with-agent-settings#cloud-agents).

If you have any questions or require assistance regarding these changes, contact ThousandEyes Support.

## 2026-03-12

### Endpoint Agent Client Version 2.35.1

The following enhancements have been made to the Endpoint Agent client:

#### macOS

* Fixed an issue where the Endpoint Agent failed to detect VPN connections on macOS when using Zscaler client version 4.4 or later.

### TCP-Based Path Trace Support for Mobile Endpoint Agents (Android)

A TCP-based path trace has been introduced as an additional option alongside ICMP for tracing network paths. Using TCP can provide more reliable visibility in environments where ICMP traffic is deprioritized, rate-limited, or blocked by network devices and firewalls.

This capability is particularly beneficial for monitoring connectivity for mobile workforce users, where networks such as home routers, public Wi-Fi, and enterprise VPNs may restrict ICMP traffic. TCP-based tracing can improve path discovery and troubleshooting accuracy in these scenarios.

This feature is now supported on all Mobile Endpoint Agents for Android.

### Mobile Endpoint Agent Android Version 1.6.0

The following enhancements have been made to the Mobile Endpoint Agent:

* Added support for location services on devices without Google Mobile Services (non-GMS).
* Improved LTE signal reporting by using **RSSNR** in place of **SINR**.
* Updated the Terms of Service screen for greater clarity.
* Improved HTTP test reporting by correcting the phase transition from `RECEIVE` to `HTTP`.
* Addressed general bug fixes and made stability improvements.

## 2026-03-10

### Chicago Webex Cloud Agent Decommission Notice

Due to changes in the Webex infrastructure, the Chicago Webex Cloud Agent will be decommissioned in 30 days. Any agent-to-agent tests or RTP tests that use this Cloud Agent as the target agent will encounter errors and will be automatically disabled after April 10th, 2026.

Other test types will not be affected unless they explicitly reference this agent as a target. You can migrate your tests to one of the following locations:

* Chicago, IL, USA (Webex Calling)
* Dallas, TX, USA (Webex Calling)
* Dallas, TX, USA (Webex Meetings)
* Montreal, Canada (Webex Meetings)
* New York, NY, USA (Webex Meetings)
* San Jose, CA, USA (Webex Meetings)
* Toronto, Canada (Webex Calling)
* Toronto, Canada (Webex Meetings)
* Vancouver, Canada (Webex Calling)

We recommend updating your configurations before the decommission date to avoid service interruptions. If you need assistance updating your tests, please contact ThousandEyes Support.

## 2026-03-05

### Mobile Experience Monitoring Dashboard Template

We have introduced the **Mobile Experience Monitoring Dashboard** template. This new dashboard is designed to help you easily monitor and analyze end-user experience on mobile devices. With a focus on application and network health, the template provides clear visualizations for your selected mobile agents or labels, making it simple to identify performance trends and resolve issues faster.

By using this template, you can:

* Gain real-time insights into mobile application and network performance.
* Quickly pinpoint issues affecting end-user experience.
* Ensure consistent monitoring and reporting across multiple account organizations.
* Reduce reliance on manual setup and external support by leveraging a ready-to-use, best-practice solution.

Learn more in our [documentation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/installing/mepa_android#building-dashboards).

## 2025-03-03

### Advance Notice on Labels to Tags UI Changes

We are making a change to how metadata is managed in ThousandEyes. By the end of March, labels across the platform will be replaced by tags, a more flexible, centralized system for organizing your tests, agents, and dashboards.

#### What's Changing

The following dedicated labels pages will no longer be available after this change:

* **Network & App Synthetics > Test Settings > Test Labels**
* **Network & App Synthetics > Agent Settings > Agent Labels**
* **Endpoint Experience > Test Settings > Test Labels**
* **Endpoint Experience > Agent Settings > Agent Labels**
* **Routing > BGP Test Labels**

Labels management will move to a single location: **Manage > Tags** in the left navigation.

In addition, all label-based filters, searches, and groupings across the platform, including in dashboards, test settings, agent settings, and views, will be updated to use tags. The guided test setup experience will also use tags going forward, and all built-in labels will be converted to built-in tags.

#### What This Means for You

* Your existing labels will be automatically migrated to tags. No action is required on your part.
* Each label will be migrated as a tag key, with the value field left empty. For example, a label named `subnet-10` will appear as the tag `subnet-10` with no value set. You can optionally add a value to any tag after migration.
* Going forward, you'll create and manage tags from the centralized Tags workspace instead of navigating to individual labels pages within each product area.

#### What's New with Tags

* Tags support key:value pairs (e.g., `env:prod`, `region:us-east`), giving you richer and more expressive metadata than flat labels allowed.
* A single workspace to manage tags across tests, agents, and dashboards.
* Improved filtering and grouping across the platform using tag key:value pairs.

No action is required. Your labels will be migrated automatically. If you have questions, reach out to your ThousandEyes account team or contact ThousandEyes Support.

## 2026-02-27

### Clearer Locations in Internet Insights Alerts

We’ve updated Internet Insights email notifications to display human-readable location names (e.g., "Cork," "Chicago") instead of internal location IDs. This improvement ensures you can immediately identify affected areas directly from your inbox.

* **Instant Recognition:** See the actual names of impacted locations in your alert emails, matching what you see in the alert rule and alert list.
* **Reduced Friction:** Eliminate the need to log in to the platform just to translate an ID into a geographic location.
* **Consistent Experience:** Enjoy a unified view of your data across both the ThousandEyes platform and your email notifications.

### Ghana Cloud Agent Decommission Notice

As part of our ongoing efforts to optimize resources and expand coverage in high-impact business areas, we will be decommissioning a small set of underutilized ThousandEyes Cloud Agent locations on Mar 31, 2026. If you are currently running tests on the following Cloud Agents, migrate them to a nearby Cloud Agent location.

#### Cloud Agent locations that will be retired on March 31st, 2026:

* Surabaya, Indonesia
* Surabaya, Indonesia - IPv6
* Yogyakarta, Indonesia
* Yogyakarta, Indonesia - IPv6
* Accra, Ghana
* Accra, Ghana - IPv6

Nearest available Jakarta-based Cloud Agent locations:

* Jakarta, Indonesia
* Jakarta, Indonesia (Alibaba ap-southeast-5)
* Jakarta, Indonesia (AWS ap-southeast-3)
* Jakarta, Indonesia (Biznet)
* Jakarta, Indonesia (GCP asia-southeast2)
* Jakarta, Indonesia (PT Telkom)
* Jakarta, Indonesia – IPv6
* Jakarta, Indonesia – IPv6 (Biznet)
* Jakarta, Indonesia – IPv6 (PT Telkom)

Nearest available Nigeria-based Cloud Agent locations:

* Lagos, Nigeria
* Lagos, Nigeria (AWS Local Zone)
* Lagos, Nigeria - IPv6

#### Action Required

If no action is taken by Mar 31, 2026 the affected Cloud Agents will be removed from your tests. Any tests relying exclusively on these Cloud Agents will be automatically disabled. If you have questions or need assistance migrating your monitoring setup, contact ThousandEyes Support.

### Recorder IDE: End of Installation Support and Deprecation Timeline

As [previously announced](https://docs.thousandeyes.com/whats-new/changelog#recorder-ide-end-of-life-and-migration-plan), the ThousandEyes Recorder IDE is deprecated. Support for **new installations has now ended** as of February 25, 2026.

**Key Dates and Actions:**

* **Installation Support Ended:** New installations are no longer supported.
* **Version Expiration:** Versions prior to v1.24.0 will stop working after **February 26, 2026**. If you must continue using the IDE, upgrade to the latest version immediately.
* **End of Life (EOL):** All existing instances of the Recorder IDE will reach End of Life on **May 27, 2026**.

**Recommended Action:** We strongly recommend migrating your test creation process to the **Google Chrome Recorder** or another SaaS-based transaction test creation option before the End of Life date.

* **Watch:** [Video Walkthrough: Importing from Google Chrome Recorder](https://app.vidcast.io/share/09e72e59-f22b-47ea-af08-e3f59aa24f63)
* **Read:** [Google Chrome Recorder Documentation](https://developer.chrome.com/docs/devtools/recorder/)

## 2026-02-24

### Endpoint Agent Client Version 2.35.0

The following enhancements have been made to the Endpoint Agent client:

#### Windows

* Resolved an issue that allowed the GlobalProtect VPN adapter to be selected for GatewayProbe results. Previously, this could display inaccurate linkspeed measurements compared to the physical adapter. Now, GatewayProbe results accurately reflect the physical adapter's linkspeed.

## 2026-02-19

### Updates to BrowserBot Subnet IP Ranges

We've updated the list of selected IP ranges that BrowserBot reserves exclusively for its own use. These IP ranges cannot be monitored externally if BrowserBot is enabled:

| Platform                         | Subnet Range                                                                  |
| -------------------------------- | ----------------------------------------------------------------------------- |
| Podman: te-browserbot-dual-stack | <ul><li>10.88.2.0/28 (IPv4)</li><li>fd15:cda9:2fb8:eaf9::/64 (IPv6)</li></ul> |
| Podman: te-browserbot-ipv4       | <ul><li>10.88.2.16/28 (IPv4)</li></ul>                                        |

{% hint style="info" %}
If Browserbot is enabled on an agent, all test types are impacted, not just BrowserBot tests.
{% endhint %}

## 2026-02-18

### Endpoint Experience Events (Controlled Availability)

Endpoint Experience Events are now available in Controlled Availability. This new feature provides enhanced visibility into endpoint-related events, helping you detect and respond to issues more effectively. Learn more about Endpoint Experience Events and how to get started in our Event Detection [documentation](https://docs.thousandeyes.com/product-documentation/event-detection).

### Mobile Endpoint Agent Android Version 1.5.1

The following enhancements have been made to the Mobile Endpoint Agent:

* Introduced support for a new mobile device management (MDM) configuration key: `CLOSE_APP_AFTER_REGISTRATION`. When enabled, this setting allows the application to automatically close upon successful completion of onboarding or registration, streamlining the setup process for end users.
* Improved application stability by addressing multiple issues that previously caused crashes and periods of unresponsiveness. Users should now experience a more reliable and consistent app experience during regular usage.
* Enhanced overall performance by identifying and resolving memory leaks within the application. These optimizations help ensure smoother operation and improved resource management.
* Updated agent content download functionality to enforce a new limit, restricting individual downloads to 10 MB. This change helps maintain optimal performance and prevents excessive resource consumption.

## 2026-02-17

### Alpine Linux End of Support Reminder

Alpine Linux 3.20 will reach End of Support on April 1st, 2026, and End of Life on June 1st, 2026.

ThousandEyes Enterprise Agents deployed as Docker containers or using the Cisco Application Hosting Framework (CAF) based on Alpine Linux 3.20 must be upgraded to the latest Agent image before then to remain functional.

{% hint style="info" %}
ThousandEyes does not support the native installation of ThousandEyes Enterprise Agents on Alpine Linux.
{% endhint %}

For more information on upgrading your agent:

* For Docker-based agents, see [Upgrading Docker Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#docker-enterprise-agents).
* For CAF Containers for Cisco Devices, see [Upgrading Cisco Devices](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#cisco-application-hosting).
* For upgrading with the SD-WAN Manager, see [Upgrading Cisco ThousandEyes Enterprise Agent Software](https://www.cisco.com/c/en/us/td/docs/routers/sdwan/configuration/system-interface/ios-xe-17/systems-interfaces-book-xe-sdwan/sdwan-thousandeyes.html#concept_crq_qsz_rqb).

### Ashburn Webex Cloud Agent Decommission Notice

[As previously announced](https://docs.thousandeyes.com/whats-new/changelog#ashburn-webex-cloud-agent-decommission-notice), we have retired the Ashburn Webex Cloud Agent.

As a result, any agent-to-agent or RTP tests that used this Cloud Agent as the target agent have been automatically disabled. Other types of tests will remain unaffected unless they specifically reference this agent as a target.

You can find the currently disabled tests in your account. Reassign them to alternative target agents and re-enable them.

Nearest available Webex Cloud Agents:

* Chicago, IL (Webex Calling)
* Chicago, IL (Webex Meetings)
* Dallas, TX (Webex Calling)
* Dallas, TX (Webex Meetings)
* Montreal, Canada (Webex Meetings)
* New York, NY (Webex Meetings)
* San Jose, CA (Webex Meetings)
* Toronto, Canada (Webex Calling)
* Toronto, Canada (Webex Meetings)
* Vancouver, Canada (Webex Calling)

For assistance updating your tests, contact ThousandEyes Support.

### Indonesia Cloud Agent Decommission Notice

As part of our ongoing efforts to optimize resources and expand coverage in high-impact business areas, we will be decommissioning a small set of underutilized ThousandEyes Cloud Agent locations in Indonesia on April 30, 2026. If you are currently running tests on the following Cloud Agents, migrate them to a nearby Jakarta-based Cloud Agent location.

**Cloud Agent locations that will be retired on April 30, 2026:**

* Surabaya, Indonesia
* Surabaya, Indonesia (IPv6)
* Yogyakarta, Indonesia
* Yogyakarta, Indonesia (IPv6)

Nearest available Jakarta-based Cloud Agent locations:

* Jakarta, Indonesia
* Jakarta, Indonesia (IPv6)
* Jakarta, Indonesia (Alibaba ap-southeast-5)
* Jakarta, Indonesia (AWS ap-southeast-3)
* Jakarta, Indonesia (Biznet)
* Jakarta, Indonesia (Biznet) (IPv6)
* Jakarta, Indonesia (GCP asia-southeast2)
* Jakarta, Indonesia (PT Telkom)
* Jakarta, Indonesia (PT Telkom) (IPv6)

#### Action Required

If no action is taken by April 30, 2026, the affected Cloud Agents will be removed from your tests. Any tests relying exclusively on these Cloud Agents will be automatically disabled.

If you have questions or need assistance migrating your monitoring setup, contact ThousandEyes Support.

### Connected Devices: Test Settings & Alerts Now Available

#### Test Settings

You can now take full control of your Connected Devices monitoring by directly creating, editing, and scheduling network and Quality of Experience (QoE) tests from the ThousandEyes platform.

Assign tests to all agents or up to 500 specific agent IDs, leverage advanced configuration options, and organize tests with intuitive tags and groups.

#### Alerts

Connected Devices now supports powerful, customizable alerting for latency, packet loss, and jitter.

Define alert conditions for all agents or targeted groups, receive real-time notifications via webhooks or email, and set severity levels to prioritize response. Enable your teams to quickly detect and resolve performance issues.

Note: These enhancements require agents to be on [version 8](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents/connected-devices-release-versions).

### 2026-02-17 Bug Fixes

* Resolved an issue where users without edit permissions received an "Internal Server Error" message when accessing the **Test Settings** page. The interface now correctly displays an "Access Denied" message to indicate the permission restriction.

## 2026-02-09

### Deprecation of "ICMP + TCP Connect" Synthetic Test Option – Endpoint Agent

The **ICMP + TCP Connect** advanced option for synthetic tests in ThousandEyes Endpoint Agent will remain available for the next 30 days. After this period, we will begin the process of removing this option, and it will be unavailable in a subsequent release.

No action is required. All tests currently configured with **ICMP + TCP Connect** will be automatically migrated to the **Auto-detect** setting, which delivers more accurate and reliable results in all cases.

## 2026-02-05

### Cloud Insights Updates

#### Cloud Inventory Test Coverage

Cloud Inventory now displays test coverage for cloud resources, allowing you to identify which resources are monitored by synthetic tests. This new feature helps you quickly spot gaps in your monitoring coverage and understand which tests are monitoring specific resources. See [Test Coverage Analysis](https://docs.thousandeyes.com/product-documentation/cloud-insights/views#test-coverage-analysis) for more information.

#### Traffic Views Enhancements

Cloud traffic views now provide greater visibility into data transfer patterns:

* Traffic Volume Metrics: View the total data transferred over customizable time periods using the new table column and time span selectors.
* Port and Protocol Details: The traffic table now includes IP port-level information, making it easier to identify specific application traffic and protocols.

See [Views: Table Tab](https://docs.thousandeyes.com/product-documentation/cloud-insights/views#table-tab) for more information.

## 2026-02-03

### Upcoming Retirement of ThousandEyes API v6

As previously communicated, ThousandEyes API v6 and all earlier API versions will reach end of life in **May 2026**. After this date, these versions will no longer be supported or available. We strongly encourage all customers to complete their migration to API v7 as soon as possible to avoid any service disruptions.

This change has the following impact:

* API v6 and earlier versions will no longer be supported or available after May 2026.
* API v7 offers significant improvements, including updated endpoints, enhanced schema, and better performance.
* Migration from API v6 to v7 may require adjustments due to schema changes. See the [API v7 migration guide](https://developer.cisco.com/docs/thousandeyes/migration-guide-overview/).

For assistance, visit our developer documentation at [ThousandEyes API v7 - Cisco DevNet](https://developer.cisco.com/docs/thousandeyes/) or contact our team.

## 2026-02-02

### New Features Added to Traffic Insights

#### New Sankey Diagram Displays Your Traffic Patterns

New Sankey visualization helps you analyze flow data patterns across your network at a glance.

* Provides visual representation of traffic flows with layered data hierarchy.
* Available as a new tab alongside the existing Table view in **Traffic Insights > Views**.
* See [Sankey Tab](https://docs.thousandeyes.com/product-documentation/traffic-insights/traffic-insights-views-and-settings#sankey-tab) for more information.

#### Flow Consolidation Improves Conversation Capture

Traffic Insights now consolidates flows from multiple devices reporting the same conversations into a single table row, giving you more realistic information about your traffic flows.

* View the number of contributing devices directly in the conversation view.
* Drill down into the raw data of each consolidated flow by clicking links within the table.
* Enable or disable the feature at **Traffic Insights > Settings > General Settings**.
* See [Flow Consolidation](https://docs.thousandeyes.com/product-documentation/traffic-insights/flow-consolidation) for more information.

#### Key-Value Pairs Enhance Subnet Tagging for Better Organizational Structure

Subnet tags now support key-value pair format for improved organization and filtering.

* Create new key-value pairs while existing simple string labels are automatically preserved as label:label format (for example, `mystring` label becomes `mystring:mystring` tag).
* New bulk tag upload available via CSV file import.
* See [Creating Optional Subnet Tags](https://docs.thousandeyes.com/product-documentation/traffic-insights/traffic-insights-configuration-guide/creating-subnet-tags) for more information.

#### Interface Filter Now Shows Relationship to Device

We redesigned the interface filter with a hierarchical tree structure for easier selection.

* Devices and their associated interfaces are now displayed in parent-child relationships.
* See [Device Data Enrichment](https://docs.thousandeyes.com/product-documentation/traffic-insights/traffic-insights-configuration-guide/discovering-devices) for more information.

#### Choose Your Device Name Source for Enhanced Naming Control

You can now configure your preferred device data source in Traffic Insights settings, giving you greater control over the device data you see.

* Choose between SNMP or NetFlow v9/IPFIX as the source for device and interface name retrieval at **Traffic Insights > Settings > General Settings**.
* See [Device Data Enrichment](https://docs.thousandeyes.com/product-documentation/traffic-insights/traffic-insights-configuration-guide/discovering-devices) for more information.

## 2026-01-30

### ThousandEyes MCP Server General Availability

The ThousandEyes MCP server is now available for all ThousandEyes customers, allowing you to connect an AI assistant directly to the ThousandEyes platform. The assistant can then use natural language to access and analyze ThousandEyes network monitoring data through a standardized interface.

For more information, see [ThousandEyes MCP Server](https://docs.thousandeyes.com/product-documentation/integration-guides/thousandeyes-mcp-server).

## 2026-01-29

### Nutanix AHV Support for Virtual Appliances

We now support installing the ThousandEyes Virtual Appliance agent (TEVA), version 0.258.0 and later, on Nutanix AHV (Acropolis Hypervisor) with Nutanix Prism Central version 7.3 and later, enabling you to deploy Enterprise Agents natively in Nutanix environments.

{% hint style="info" %}
Deployments through Prism Element (cluster-local management) are not supported.
{% endhint %}

For instructions on installing a TEVA agent, see [ThousandEyes Virtual Appliance Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-virtual-appliance-installation).

## 2026-01-28

### ThousandEyes Endpoint Agent: Serial Number Visibility

We’ve made it easier to identify and manage your devices. The Endpoint Agent now displays device Serial Numbers across key workflows—including Agent Settings, Single Agent View, and Views—for streamlined device identification and inventory management.

You can now search for and filter agents by Serial Number in these sections. This information is also available through the Endpoint Agent public APIs, enabling faster, more accurate tracking and troubleshooting of individual devices.

{% hint style="info" %}
The Serial Number will be visible for agents running on version 2.31.0 or higher.
{% endhint %}

### Updated Heat Map Visualization in Endpoint Agent View

The heat map in Endpoint Agent View now uses a smooth color gradient rather than six fixed colors. This update helps you identify performance changes more easily and provides clearer insight into endpoint experience trends.

## 2026-01-27

### Mobile Endpoint Agent Android Version 1.5.0

The following enhancements have been made to the Mobile Endpoint Agent:

* Mobile Endpoint Agent now supports TCP Connect for ping tests, providing reliable connectivity checks even when ICMP is blocked.
* Fixed an issue that caused the app to crash when encountering unknown hosts.
* The app now checks for network interface availability before use to prevent exceptions.
* Metrics from endpoints in HTTP Server tests no longer display negative values.

## 2026-01-26

### Alpine Linux End of Support Reminder

Alpine Linux 3.20 is now in the End of Installation Support phase. It will reach End of Support on April 1st, 2026, and End of Life on June 1st, 2026.

ThousandEyes Enterprise Agents deployed as Docker containers or using the Cisco Application Hosting Framework (CAF) based on Alpine Linux 3.20 must be upgraded to the latest Agent image before then to remain functional.

{% hint style="info" %}
ThousandEyes does not support the native installation of ThousandEyes Enterprise Agents on Alpine Linux.
{% endhint %}

For more information on upgrading your agent:

* For Docker-based agents, see [Upgrading Docker Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#docker-enterprise-agents).
* For CAF Containers for Cisco Devices, see [Upgrading Cisco Devices](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#cisco-application-hosting).
* For upgrading with the SD-WAN Manager, see [Upgrading Cisco ThousandEyes Enterprise Agent Software](https://www.cisco.com/c/en/us/td/docs/routers/sdwan/configuration/system-interface/ios-xe-17/systems-interfaces-book-xe-sdwan/sdwan-thousandeyes.html#concept_crq_qsz_rqb).

### Adaptive Alerting Is Now Available for Endpoint Scheduled Tests

We are pleased to announce that Adaptive Alerting is now available for Endpoint scheduled tests. This extends our intelligent alerting capabilities to your endpoint monitoring, helping you reduce alert fatigue and focus on the performance issues that truly impact your remote workforce.

Adaptive Alerting learns what's normal for your users and automatically detects statistically significant deviations based on historical patterns and the scope of an issue.

Key benefits for Endpoint Agent monitoring:

* **Smarter Alerts for a Dynamic Workforce:** Adaptive Alerting can intelligently distinguish between minor, isolated fluctuations (like a single user's brief Wi-Fi dip) and widespread, persistent problems that require attention. It also learns to identify consistently problematic devices by giving more weight to issues that reoccur on the same endpoint over time.
* **Drastically Reduced Alert Fatigue:** Move beyond rigid "X agents over Y rounds" conditions. By analyzing historical patterns and the statistical probability of an issue, Adaptive Alerting automatically filters out transient noise and insignificant anomalies, ensuring your team is only notified for meaningful performance degradations.
* **Simplified Configuration:** Instead of manually defining complex agent and round counts, simply enable adaptive detection and choose a single sensitivity level (High, Medium, or Low). Adaptive Alerting then automatically applies the appropriate probability thresholds to match your monitoring needs.

Adaptive Alerting is now the default method for all new Endpoint Scheduled Test alert rules. You can also update your existing Endpoint Scheduled Test alert rules to use this new, more intelligent detection method.

For more information on how this feature works, see [Creating and Editing Alert Rules: Adaptive Alerting Overview](https://docs.thousandeyes.com/product-documentation/alerts/creating-and-editing-alert-rules#adaptive-alerting-overview).

## 2026-01-21

### Endpoint Dynamic Tests Metrics in OpenTelemetry

Endpoint dynamic tests metrics are now supported in ThousandEyes for OpenTelemetry. For a complete list of supported data, see [ThousandEyes for OpenTelemetry Data Models](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/data-model).

## 2026-01-19

### Endpoint Agent Client Version 2.31.0

The following enhancements have been made to the Endpoint Agent client:

#### All Platforms

* The agent’s gateway detection logic has been enhanced to more reliably identify gateway connections when a VPN is active. This update ensures local network and gateway metrics are visible, even if VPN clients modify or obscure standard network routes.
* The agent now reports the machine’s serial number, when available, on supported platforms. This improvement provides more accurate device identification and simplifies asset management for administrators.
* Previously, the agent only recognized TCP rules and did not consider the protocol when matching VPN bypass rules. This issue has been fixed. The agent now correctly evaluates forwarding rules by protocol for dynamic tests, ensuring VPN bypass rules are handled accurately.
* The agent no longer supports Cisco ZTA versions earlier than 5.1.7. Upgrade to version 5.1.7 or later to continue receiving updates and support.

#### Windows

* The default NPCAP library distributed with the installer is version **1.86.**

## 2026-01-16

### Ashburn Webex Cloud Agent Decommission Notice

Due to changes in the Webex infrastructure, the Ashburn Webex Cloud Agent will be decommissioned in 30 days. Any agent-to-agent tests or RTP tests that use this Cloud Agent as the target agent will encounter errors and will be automatically disabled after February 16th, 2026.

Other test types will not be affected unless they explicitly reference this agent as a target. You can migrate your tests to one of the following locations:

* Chicago, IL (Webex Calling)
* Chicago, IL (Webex Meetings)
* Dallas, TX (Webex Calling)
* Dallas, TX (Webex Meetings)
* Montreal, Canada (Webex Meetings)
* New York, NY (Webex Meetings)
* San Jose, CA (Webex Meetings)
* Toronto, Canada (Webex Calling)
* Toronto, Canada (Webex Meetings)
* Vancouver, Canada (Webex Calling)

We recommend updating your configurations before the decommission date to avoid service interruptions. If you need assistance updating your tests, contact ThousandEyes Support.

### Upcoming Change to Path Visualization View

To simplify the Path Visualization interface and focus our efforts on its core diagnostic features, we will be removing the temporary drag-and-drop functionality for reordering nodes.

Key details:

* **What's Changing:** The ability to temporarily rearrange nodes by dragging them will be removed.
* **Why We're Making This Change:** This allows us to streamline the user experience and dedicate development to enhancing the core analytical capabilities of Path Visualization.
* **When It Will Happen:** This change will take effect after **February 2, 2026**.

This update only affects the temporary visual ordering of nodes; all test data and path analysis features will continue to function as they do today.

## 2026-01-07

### Required Upgrade for all Docker-Based Enterprise Agents

[Recent runc security fixes](https://docs.thousandeyes.com/whats-new/changelog#linux-docker-container-based-enterprise-agents-required-update) introduced a [regression](https://github.com/opencontainers/runc/issues/5007). runc has fixed this issue, and we now require all customers using Docker-based Enterprise Agents to upgrade runc, either directly to version 1.3.4 or later, or by upgrading `docker-ce`.

{% hint style="info" %}
If you are on SUSE (SLES), you will need to upgrade to runc version 1.4.0 or later. This is because the Docker package shipped in SUSE (SLES) is from the SUSE repository and not from [Docker Inc](https://docs.docker.com/engine/install/#installation-procedures-for-supported-platforms).
{% endhint %}

{% hint style="info" %}
You may also need to update your seccomp profiles and redeploy the Enterprise Agent container if you are on the wrong profile. See the recommended steps below to confirm whether you need to update the seccomp profile.
{% endhint %}

**Recommended Steps**

Confirm whether the seccomp profiles need to be updated:

```
$ cat /var/docker/configs/te-seccomp.json | grep openat2
        "openat2",
```

If the command returns nothing, then the correct profile is currently active, and you can ignore the steps marked as **Optional** below.

If you want to upgrade runc directly:

1. Download the correct binary from their release pages, under assets: [runc Releases](https://github.com/opencontainers/runc/releases).
2. Use the `which runc` command to identify where the existing runc binary is located.
3. Replace the runc binary in your filesystem with the newly downloaded binary.
4. **Optional**: Update the `seccomp` profile and re-deploy the Enterprise Agent container if required. For instructions, see [Redeploying Docker-Based Enterprise Agents for runc Security Fixes](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/troubleshooting/redeploy-docker-ea-runc).

If you want to upgrade `docker-ce`:

1. Upgrade `docker-ce`, to ensure runc is the latest version (at least v1.3.4).
2. Verify the runc version using `docker info` and `runc --version`.
3. **Optional**: Update the `seccomp` profile and re-deploy the Enterprise Agent container if required. For instructions, see [Redeploying Docker-Based Enterprise Agents for runc Security Fixes](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/troubleshooting/redeploy-docker-ea-runc).

Once you have upgraded runc either directly or through docker-ce upgrade, verify runc version after the upgrade via runc --version or docker info commands.

## 2025-12-22

### Wireless Active Testing with ThousandEyes Endpoint Agent

The ThousandEyes Endpoint Agent is now available as part of the Wireless Active Testing solution on Cisco C9172H wireless access points. This integration empowers your network with advanced monitoring and testing capabilities, directly from the access point.

The Endpoint Agent utilizes the radios on your Cisco C9172H access point to continuously rotate through SSIDs and BSSIDs across the 2.4 GHz, 5 GHz, and 6 GHz bands. It performs both pre-connection and synthetic tests, enabling seamless, real-time monitoring of your Wi-Fi network’s performance.

Key features include:

* Pre-connection tests, such as Wi-Fi association and authentication validation
* Synthetic connectivity tests performed using the access point radio
* Automated rotation across BSSIDs and SSIDs for comprehensive coverage

You can learn more about Wireless Active Testing in the following documentation:

* [Wireless Active Testing with ThousandEyes](https://www.cisco.com/c/en/us/td/docs/wireless/controller/9800/17-18/config-guide/b_wl_17_18_cg/m_thousandeyes-integration-enhancements.html)
* [Cisco Active Testing for Wireless with ThousandEyes On-Prem Deployment Guide](https://www.cisco.com/c/en/us/td/docs/wireless/controller/9800/technical-reference/active-testing-wireless-on-prem-dg.html)
* [Configuring Wireless Active Testing with ThousandEyes](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/wireless-active-testing)

## 2025-12-19

### Enhanced User Experience in Endpoint Agent View

Following the success and positive feedback from the Endpoint Agent Views 2.0 General Availability, we are introducing new enhancements to make troubleshooting easier, shorten the learning curve, and increase adoption across all user levels—especially for Tier-1 support and help desk teams. These updates help IT and Collaboration teams resolve individual employee issues more quickly and efficiently.

#### Key enhancements:

* Simplified summary cards: Intuitive summary cards are now the default entry point, giving you a quick overview of performance. For a more detailed view, you can use the heatmaps to gain deeper insights.
* Multi-metric timeline for faster correlation: The new multi-metric timeline view lets you quickly compare different performance metrics. Users can see how various factors interact, supporting faster and more informed troubleshooting.
* Improved usability and speed: The interface has been streamlined for better usability and faster performance, delivering a smoother workflow for all users.

For more details, see [Endpoint Agent Views](https://docs.thousandeyes.com/product-documentation/end-user-monitoring/viewing-data/agent-views)

### Login Page Now Supports Region Selection

ThousandEyes now allows users to choose their authentication region directly from the login page. This enhancement is based on feedback from customers who manage organizations across multiple regions and need more control over where authentication occurs. The new option complements the existing region selector available after authentication within the ThousandEyes platform.

A region drop-down is now displayed on the [login page](https://app.thousandeyes.com/login) with the following options:

* **Default** (preselected): Uses ThousandEyes’ standard region-routing logic. If your user account exists in only one region, you will automatically be routed to the default account group in that region.
* **US1**, **US2**, or **EU** (optional): Users with accounts in multiple regions can select a specific region to force authentication there.

{% hint style="info" %}
If you select a region where your user record does not exist, you will see an error message. Switch to a different region or choose **Default** to allow ThousandEyes to route you automatically.
{% endhint %}

## 2025-12-17

### Cisco ThousandEyes Mobile Endpoint Agent for Honeywell

We’re pleased to announce support for GSM-enabled Honeywell devices with the ThousandEyes Mobile Endpoint Agent (MEPA) for Android. Honeywell devices running Android 11 or later are supported starting with MEPA version 1.4.2, available on Google Play.

This release brings ThousandEyes visibility to rugged Honeywell enterprise devices used in logistics, manufacturing, retail, aviation, field operations and more.

**Key features:**

* Scheduled ICMP & HTTP testing in the background.
* Path visualization, dashboards, alerts, device health, and experience score.
* Mobile telemetry: RSSI, RSRP, RSRQ, SINR, network generation, and subtype.
* MDM deployment through Intune, SOTI, Workspace ONE, and other platforms.

CPU metrics, TCP protocol for network tests, dynamic tests, real user tests, and wireless metrics (Retransmission Rate, Roaming Events, and Channel Swap Events) are not supported on mobile devices. The minimum test interval is 5 minutes, with up to 4 concurrent tests supported.

For more information, see: [MEPA Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/installing/mepa_android) and [Silent Deployment](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/installing/mepa-silent-installation).

## 2025-12-10

### Alpine Linux End of Installation Support

Alpine Linux 3.20 will reach End of Installation Support on January 1st, 2026, and End of Life on June 1st, 2026.

ThousandEyes Enterprise Agents deployed as Docker containers or using the Cisco Application Hosting Framework (CAF) based on Alpine Linux 3.20 must be upgraded to the latest Agent image before then to remain functional.

{% hint style="info" %}
ThousandEyes does not support the native installation of ThousandEyes Enterprise Agents on Alpine Linux.
{% endhint %}

For more information on upgrading your agent:

* For Docker-based agents, see [Upgrading Docker Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#docker-enterprise-agents).
* For CAF Containers for Cisco Devices, see [Upgrading Cisco Devices](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#cisco-application-hosting).
* For upgrading with the SD-WAN Manager, see [Upgrading Cisco ThousandEyes Enterprise Agent Software](https://www.cisco.com/c/en/us/td/docs/routers/sdwan/configuration/system-interface/ios-xe-17/systems-interfaces-book-xe-sdwan/sdwan-thousandeyes.html#concept_crq_qsz_rqb).

## 2025-12-09

### Cloud Insights Adds Support for Azure Traffic Analysis with VNet Flow Logs

Cloud Insights now supports Azure virtual network (VNet) flow logs, providing new visibility into cloud network traffic across Azure-hosted applications and services. With this update, you can leverage Cloud Insights against your Azure cloud environment to:

* Analyze your network flows.
* Quickly surface top talkers.
* Identify transient traffic spikes or dips through stacked views.

In addition, VNet traffic flows are correlated with configuration change events in **Cloud Insights > Inventory** and **Cloud Insights > Views**, as well as with your test framework at **Network & App Synthetics > Views**, streamlining root cause analysis of changes in traffic patterns.

For integration setup instructions, see [Azure for Cloud Insights](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-built-integrations/azure-for-cloud-insights). For information about viewing your flow log data, see [Cloud Insights](https://docs.thousandeyes.com/product-documentation/cloud-insights).

## 2025-12-05

### Enhanced Log Access for Virtual and Physical Appliance Agents

Previously, the `thousandeyes` user used for SSH-based agent management only had access to a very limited set of files and commands. This limited the ability to perform basic diagnostics without support.

We have now expanded the troubleshooting capabilities for ThousandEyes appliance agents by providing additional commands that can be run without elevated privileges.

For more information, see [Troubleshooting Capabilities](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/connecting-to-the-thousandeyes-virtual-appliance-using-ssh-mac-linux#troubleshooting-capabilities).

## 2025-12-04

### Recorder IDE End of Life and Migration Plan

Cisco ThousandEyes is deprecating the ThousandEyes Recorder IDE, which was previously used to locally create scripts for transaction tests. The recorder will be phased out over the coming months, outlined by the timeline below:

* December 4th, 2025: Recorder IDE deprecation. End of support for improvements or updates.

{% hint style="warning" %}
Per the [Recorder IDE Support Policy](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/getting-started/thousandeyes-recorder#recorder-ide-support-policy), versions prior to v1.24.0 will stop working after February 26, 2026. If you require use of the Recorder IDE beyond that, ensure you upgrade to the latest version as soon as possible.
{% endhint %}

* March 4th, 2026: End of Installation Support.
* May 27th, 2026: End of Life.

#### Why are we deprecating the Recorder IDE?

Maintaining the Recorder IDE and its embedded Chromium browser has introduced significant complexity and operational overhead for both customers and our engineering teams. Monthly updates are required to comply with organizational infosec policies, making this approach unsustainable.

#### Next Steps

Cisco ThousandEyes recommends you migrate your test creation process to the Google Chrome recorder (or another SaaS-based transaction test creation option) before the End of Life date.

You can watch a video walkthrough of how to use the Google Chrome recorder import feature here:

{% embed url="<https://app.vidcast.io/share/09e72e59-f22b-47ea-af08-e3f59aa24f63>" %}

For more information, see the [Google Chrome Recorder](https://developer.chrome.com/docs/devtools/recorder/) documentation.

### Introducing a Modernized Test Settings Experience

We are rolling out a redesigned and improved interface for creating new tests. This update streamlines the configuration process with a more intuitive layout, clearer guidance, and faster workflows.

Key improvements:

* Start New Tests Faster: The new **+ Add New Test** button opens a **Quick Create** menu, giving you one-click access to any test type directly from the test list. This lets you begin configuration immediately without navigating away from your current view.
* Simplified Interface: The primary configuration screen is now cleaner and easier to navigate. Less-frequently used options have been reorganized into more intuitive, logical groups.
* Direct Label Assignment: You can now assign items directly to labels within the test configuration, reducing extra steps.
* Configure Tests with More Confidence: Get clearer guidance on settings and options with enhanced inline help available throughout the test creation workflow.

This update is part of our ongoing effort to make test configuration simpler and more efficient. For more information, see our documentation on [Working with Test Settings: Adding Tests Manually](https://docs.thousandeyes.com/product-documentation/tests/working-with-test-settings#adding-tests-manually).

### Reminder About Removing Duplicate Devices

As announced [previously](https://docs.thousandeyes.com/whats-new/changelog#removing-duplicate-devices), to enhance our device monitoring efficiency, we are revising our device discovery process to eliminate duplicated devices identified through multiple scans. This change will take effect on December 11, 2025.

On December 11, we will perform a one-time cleanup of all monitored and unmonitored duplicate devices. Duplicates will be identified as devices sharing the same IP address, agent, MAC address, and engine ID, and will be automatically removed.

**Unmonitored Duplicates**

For unmonitored devices, we do not anticipate any interruptions to your experience, as these devices do not monitor or report data to the platform. However, if you have a scheduled discovery that includes these devices, they may reappear in your environment after the cleanup.

**Monitored Duplicates**

For monitored duplicates, the primary device will continue to be monitored and will continue reporting data to the platform.

{% hint style="warning" %}
The historical data of any duplicate devices removed will be lost, and any alerts triggered by them will be automatically closed.
{% endhint %}

If you have any questions, contact ThousandEyes Support.

## 2025-12-03

### SAML Certificate Renewal Reminder

{% hint style="info" %}
If you have already updated your SAML certificate, you can disregard this reminder.
{% endhint %}

The ThousandEyes SAML certificate has been renewed, and the updated certificate is now available in the SAML metadata.

If your organization continues using the old certificate, users may be unable to log into ThousandEyes after December 10th, 2025, and the single logout feature may also be impacted.

If you have not yet updated your configuration:

* For dynamic Single Sign-On (SSO) configurations, your identity provider server will automatically receive the updated certificate.
* For static or metadata-file SSO configurations, follow the [ThousandEyes SAML setup instructions](https://docs.thousandeyes.com/product-documentation/user-management/authentication/how-to-configure-single-sign-on-with-metadata#thousandeyes-side-setup) to update to the new certificate.

### Updates to Cloud Insights

#### AWS Transit Gateway Flow Logs Now Available

Cloud Insights now supports AWS Transit Gateway flow logs, which you can view in a dedicated tab in **Cloud Insights > Views**. This enhancement enables efficient and cost-effective monitoring of cloud network traffic between multiple VPCs and other interconnects (such as AWS Direct Connect or VPNs) linked through your Transit Gateway. Transit Gateway flow logs provide high-level, cross-cloud visibility of network traffic while significantly reducing the volume of logs ingested by Cloud Insights - by up to 80% compared to using only VPC flow logs.

For instructions on sending Transit Gateway flow logs to ThousandEyes, see [Creating the AWS Flow Logs Monitoring Integration](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-built-integrations/aws-for-cloud-insights#creating-the-aws-flow-logs-monitoring-integration-for-cloud-insights). For information about viewing your Transit Gateway flow log data, see Cloud Insights [Views](https://docs.thousandeyes.com/product-documentation/cloud-insights/views), and for a comparison of Transit Gateway and VPC flow logs, see [Flow Log Types](https://docs.thousandeyes.com/product-documentation/cloud-insights/flow-log-types).

#### Agent-to-Agent Tests Now Supported

You can now view agent-to-agent tests in the **Cloud Configuration** layer within **Network & App Synthetics > Views**. Agent-to-agent tests provide definitive point-to-point network measurements, enabling Network Engineering and Operations teams to prove network performance, visualize topology with directionality, and track configuration changes along the test path in cloud environments. This capability addresses a critical gap in the troubleshooting workflow for network performance validation between virtual networks.

For more information, see [Supported Test Types](https://docs.thousandeyes.com/product-documentation/cloud-insights#supported-test-types).

#### Track Multiple Test Layers with Multi-Source Views

Get at-a-glance visibility across multiple test dimensions within **Network & App Synthetics > Views** with Cloud Insights' new multi-source views. This enhancement accelerates root cause analysis by correlating metrics across web, network, routing, and cloud infrastructure layers, making it easier to identify the source and propagation of issues throughout the digital experience. Compare up to five metrics from different test layers, plus time-correlated inventory events, on a single timeline, with clear identification of each metric’s interval and context.

For more information, see [Multi-Source Views](https://docs.thousandeyes.com/product-documentation/cloud-insights/views#multi-source-views).

#### AWS Flow Log Ingestion Streamlined with New Parquet Support

You can now ingest AWS flow logs in Parquet format for both VPC and Transit Gateway integrations, offering a more streamlined option for data ingestion.

While the traditional text format is still fully supported, you can now configure your AWS integrations to send flow logs in Apache Parquet, a columnar storage format optimized for large-scale data processing. The highly compressed nature of Parquet can significantly lower data storage and transfer costs within your AWS environment while enabling efficient ingestion due to its design for fast data analytics.

When configuring your flow log publishing in AWS, you can now select **Parquet** as the log file format. For setup instructions, see the following sections in the [AWS for Cloud Insights Integration Guide](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-built-integrations/aws-for-cloud-insights): [Configure VPCs to Publish Flow Logs in AWS](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-built-integrations/aws-for-cloud-insights#configure-vpcs-to-publish-flow-logs-in-aws) and [Configure Transit Gateways to Publish Flow Logs in AWS](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-built-integrations/aws-for-cloud-insights#configure-transit-gateways-to-publish-flow-logs-in-aws).

To learn more, see the official [Apache Parquet website](https://parquet.apache.org/) and the [AWS documentation on columnar formats](https://docs.aws.amazon.com/athena/latest/ug/columnar-storage.html).

## 2025-11-27

### Silent Deployment for the Mobile Endpoint Agent (Samsung, Zebra, and Honeywell)

We’re pleased to announce the availability of silent deployment for the Mobile Endpoint Agent on Samsung, Zebra, and Honeywell devices, starting with version 1.4.2. This update is now live on Google Play and supports Android 11 and later.

With this release, organizations can deploy the agent using zero-touch methods, eliminating the need for end-user interaction. Manual deployment options remain fully supported.

#### Key features:

* Silent deployment is available on Samsung, Zebra, and Honeywell devices. Administrators can automatically grant the required permissions: `REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` and `SCHEDULE_EXACT_ALARM`.
* Each OEM supports silent deployment through its dedicated configuration tool:
  * Samsung: Knox Service Plugin
  * Zebra: Zebra OEMConfig
  * Honeywell: Honeywell UEMConnect (currently in Open Beta) These tools enable the automatic granting of necessary permissions on their respective platforms.
* A new MDM configuration key, `auto_register_agent`, allows the app to launch automatically and start registration with ThousandEyes.

{% hint style="info" %}
Android devices from manufacturers other than those listed above may still require manual steps for mass deployment.
{% endhint %}

For implementation guidance, see our [Documentation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/installing/mepa-silent-installation).

## 2025-11-26

### Rebalancing Cluster Agent Tasks

Previously, we automatically rebalanced agent tasks in the cluster when an agent was disabled or deleted. We have now improved task distribution across Enterprise Agents by introducing real-time load-based rebalancing triggers. The system now monitors agent load continuously, and automatically rebalances when an agent becomes overloaded. This ensures smoother performance, a reduction in missed rounds, and avoids "no data" gaps in high-volume scenarios.

## 2025-11-25

### Connected Devices: Device Agent v7 Release

Device Agent version 7 introduces significant enhancements, including support for remote updates and expanded configuration options for core agent tests. This release supports all agent types, including the embedded Device Agent, Docker, Raspberry Pi, and Whitebox 8/8+/9 support.

#### Remote Updates

Device Agent v7 now supports remote self-updates, independent of device firmware. Once the agent is integrated into the firmware, Cisco ThousandEyes cloud determines which agent version to deploy at runtime. This process can be coordinated in advance with your ISP or device manufacturer to avoid updates during peak hours.

Remote agent updates do not require a device restart. If an update cannot be downloaded or verified, the existing version continues to run without interruption.

#### Additional Enhancements

* **Faster Agent Startup**: The agent now launches operations immediately, reducing time from boot to availability. This is especially valuable for verifying speeds during router installation.
* **TCP Support for DNS Queries**: Use TCP for DNS if UDP traffic is blocked by a firewall.
* **IPv6 Default**: HTTP speed and jitter tests now default to IPv6 when no protocol is specified.
* **ICMP Ping Update**: You can now configure timeout per packet and packet size.
* **Traceroute Update**: Configure retries for failed hops, adjust packet delay, set packet size, and define the maximum number of hops.
* **HTTP Speed Test Enhancement**: The system now supports parsing HTTP test results with throughput up to 73,786,976,294 Gbps, increasing the maximum bit rate for video tests. The previous upper limit was 17.180 Gbps.

For more information, see our [Documentation](https://docs.thousandeyes.com/product-documentation/connected-devices/device-agents).

## 2025-11-21

### Linux Docker Container-Based Enterprise Agents: Required Update

{% hint style="info" %}
An announcement about this required update was published [earlier this month](#id-2025-11-13). This Changelog entry contains important revisions to the required user actions.
{% endhint %}

This section applies to customers whose ThousandEyes implementation includes Enterprise Agents deployed in Linux Docker containers, and who encounter the following error upon upgrading **runc** or **docker**:

```
Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: error closing exec fds: get handle to /proc/thread-self/fd: unsafe procfs detected: openat2 fsmount:fscontext:proc/thread-self/fd/: function not implemented: unknown
```

If this applies to your agents, you must perform the update steps described below.

#### Background

Due to recent **runc** security fixes (for [CVE-2025-31133](https://github.com/opencontainers/runc/security/advisories/GHSA-9493-h29p-rfm2), [CVE-2025-52881](https://github.com/opencontainers/runc/security/advisories/GHSA-cgrx-mc8f-2prm), and [CVE-2025-52565](https://github.com/opencontainers/runc/security/advisories/GHSA-qw9x-cqr3-wc7r)), you must manually update your agents' **seccomp** profiles so that they will operate properly.

#### Actions We've Taken

We have updated our **seccomp** profile to be compatible with the latest fixes to **runc**.

#### Actions You Must Take

To avoid errors in your Docker-based Enterprise Agents, do the following basic steps for each agent.

1. In the currently running Enterprise Agent container, delete any existing **te-seccomp.json** file.
2. Using **docker inspect**, extract the **NAME** and **HOST\_VOL\_AGENT\_DIR** values.
3. In the ThousandEyes platform UI, redeploy the Enterprise Agent container to reload the new seccomp profile.

For detailed instructions, see [Redeploying Docker-Based Enterprise Agents for runc Security Fixes](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/troubleshooting/redeploy-docker-ea-runc).

## 2025-11-20

### Streamline Test Creation with the Quick Create Menu

To improve workflow efficiency and reduce page load times, we've added a new **Quick Create** menu to the **Test Settings** page. This allows you to start configuring any test type directly from the test list, without navigating to a separate page first.

Key features:

* Faster Test Setup: Skip the extra page load and start configuring your test immediately.
* Improved Workflow: Stay on the **Test Settings** page while choosing a test, so you don't lose your filters or context.
* One-Click Access: Jump directly into the configuration page for any test type from a single, convenient menu.

This update streamlines the test creation process, making it faster and more intuitive to manage your monitoring. The test configuration pages themselves have not changed. For more information, see our documentation on [Test Settings](https://docs.thousandeyes.com/product-documentation/tests#create-a-single-test).

### OAuth 2.0 Authentication Support for OpenTelemetry Integration

OAuth 2.0 is now available as an authentication method for ThousandEyes OpenTelemetry integrations. This provides a modern, secure, and scalable alternative to the existing authentication methods: Basic, Token, and Custom Auth types.

To set up OAuth 2.0 authentication for an OpenTelemetry integration, see [Getting Started with ThousandEyes for OpenTelemetry](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/getting-started). The new **OAuth Client Credentials** option appears alongside Basic, Token, and Custom Auth types.

### Expansion of OpenTelemetry Data with Endpoint Local Network Metrics

We are excited to announce that a new set of telemetry data can now be streamed using the [ThousandEyes for Opentelemetry](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry) integration. This update includes endpoint agent local network metrics, enabling you to further streamline your end-user experience monitoring.

For a complete list of available metrics, see the [ThousandEyes for OpenTelemetry Data Models](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/data-model) for both Data Model v1 and v2.

### Expanded Network Outages Catalog in Internet Insights

We have expanded our Internet Insights catalog by adding 100+ new providers and ASNs to enhance network coverage, improve insights, and bring broader network visibility. Find your providers at [**Internet Insights > Catalog Settings > Providers**](https://app.thousandeyes.com/internet-insights/catalog-settings/?tab=providers).

## 2025-11-19

### Mobile Endpoint Agent Android Version 1.4.0

The following enhancements have been made to the Mobile Endpoint Agent:

* Enhanced network probes to collect and display detailed wireless performance metrics, enabling improved monitoring and troubleshooting of wireless connections.
* Simplified the user interface and background logic by removing telephony-related features from devices that do not support telephony capabilities. This ensures a more streamlined experience for users of non-telephony devices.
* Prevented the installation and execution of the agent on Android Open Source Project (AOSP) devices that do not include Google Mobile Services (GMS). This ensures compatibility and prevents unsupported configurations.
* Modified SSL certificate handling to disable built-in certificate verification if configured by user, and permit the use of user-installed Certificate Authorities (CAs). This change provides users with greater flexibility in managing secure connections. **Note:** Disabling SSL certificate verification may reduce security. Ensure you trust the user-installed CAs.

## 2025-11-14

### Event Summaries Are Now in the Cisco AI Assistant

Previously, AI-generated summaries for single or recurring events were shown in standalone modals. These summaries have now been moved into the Cisco AI assistant panel, allowing you to ask follow up questions and dive deeper into the summaries.

For more information on event detection, see [Event Detection](https://docs.thousandeyes.com/product-documentation/event-detection).

## 2025-11-13

### Linux Docker Container-Based Enterprise Agents: Required Update

{% hint style="info" %}
This Changelog announcement has since been updated with important revisions to the required user actions. See the [latest entry](#id-2025-11-21).
{% endhint %}

If your ThousandEyes implementation includes Enterprise Agents deployed in Linux Docker containers, you must perform the update steps described below.

#### Background

Due to recent **runc** security fixes (for [CVE-2025-31133](https://github.com/opencontainers/runc/security/advisories/GHSA-9493-h29p-rfm2), [CVE-2025-52881](https://github.com/opencontainers/runc/security/advisories/GHSA-cgrx-mc8f-2prm), and [CVE-2025-52565](https://github.com/opencontainers/runc/security/advisories/GHSA-qw9x-cqr3-wc7r)), you must manually update your agents' **seccomp** profiles so that they will operate properly.

Without this update, your agents will eventually encounter the following error:

`unsafe procfs detected: openat2 fsmount:fscontext:proc/thread-self/fd/: <err>`

#### Actions We've Taken

We have updated our **seccomp** profile to be compatible with the latest fixes to **runc**.

#### Actions You Must Take

To avoid errors in your Docker-based Enterprise Agents, do the following for each agent:

1. Delete any existing **te-seccomp.json** file.

   `rm /var/docker/configs/te-seccomp.json`
2. Fetch the latest Enterprise Agent **configure\_docker.sh** file.

   `curl -Os https://downloads.thousandeyes.com/bbot/configure_docker.sh`
3. Make the **configure\_docker.sh** file executable.

   `chmod +x configure_docker.sh`
4. As superuser, execute the **configure\_docker.sh** file.

   `sudo ./configure_docker.sh`
5. Restart the Docker daemon.

   `systemctl restart docker`
6. Check the status of the Docker daemon.

   `systemctl status docker`

### Cisco Application Hosting Framework (CAF) version 5.1.3

CAF version 5.1.3 has now been released. This release is intended to replace the 5.1.2 image on all supported Cisco devices.

For upgrade instructions, see [Upgrading Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#cisco-application-hosting).

**New Features**

CAF 5.1.3 adds support for the CAF infrastructure's built-in application health probe. This assists in troubleshooting issues that may prevent an agent from connecting with the ThousandEyes platform.

For more information on the application health probe, see [Troubleshooting CAF Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/troubleshooting/troubleshooting-caf-agents).

CAF 5.1.3 also adds support for configuring alternative repositories for the operating system and ThousandEyes repositories.

For more information on configuring alternate repositories, see [Configuring a Local Mirror of the ThousandEyes Package Repository](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/configuring-a-local-mirror-of-the-thousandeyes-package-repository#cisco-application-hosting-framework-caf-agents).

**MD5 Checksum Verification**

ThousandEyes recommends validating the checksum of downloaded packages. The md5 checksums for the CAF version 5.1.3 images are:

* 73e6ecc320284f4112c95523deca2f39 thousandeyes-enterprise-agent-aarch64-5.1.3.cisco.tar
* ff5849fa1b0379c2f5a7319ff0d9c90a thousandeyes-enterprise-agent-x86\_64-5.1.3.cisco.tar

## 2025-11-12

### ThousandEyes API v6 End-of-Life Reminder

Support for API v6 ended on May 27, 2025, and all API v6 endpoints will be decommissioned after May 27, 2026. After this date, any integration or workflow relying on API v6 will no longer function.

Why migrate now?

* API v7 is the only version supported by the latest tools and SDKs, including the Terraform Provider v3, ThousandEyes Java SDK, and Python SDK.
* API v7 continues to expand with new endpoints, improved standardization, and enhanced performance.
* Migrating early ensures a smoother transition and allows you to take full advantage of our support and resources.

To help you with the migration, we’ve prepared a comprehensive API v7 [Migration Guide](https://developer.cisco.com/docs/thousandeyes/migration-guide-overview/).

We strongly encourage all customers to complete their migration to API v7 as soon as possible to avoid any disruptions.

## 2025-11-10

### New BGP Routing Data Table View

The new routing data table presents Autonomous System (AS) paths for BGP routes in a clear, structured view. It complements the graphical route visualization by providing an alternative, data-driven way to analyze AS paths. The table format enhances visibility into route changes over time, making it easier to monitor and understand BGP path behavior. For more details, see [Routing Data Table](https://docs.thousandeyes.com/product-documentation/tests/bgp-tests/using-the-bgp-route-visualization-view#routing-data-table).

## 2025-11-05

### Test Version History Is Now Available in Test Settings

You can now view and revert to previous saved versions of a test. Selecting a previous version from the drop-down list will load that configuration into the test settings form, which you can then save and enable for the test.

For more information, see [Revert to a Previous Test Version](https://docs.thousandeyes.com/product-documentation/tests#reverting-to-a-previous-test-version).

### New Cloud Agents

New Cloud Agents have been added in the locations listed below. For a full list of Cloud Agents, see [ThousandEyes Cloud Agent Locations](https://www.thousandeyes.com/product/cloud-agents).

* Ankara, Turkey (Turk Telecom)
* Ankara, Turkey (Turk Telecom) (IPv6)
* Casablanca, Morocco

## 2025-11-04

### Understand Why an Alert Triggered with Adaptive Alert Explainability

To help you understand why an adaptive alert was triggered, we've introduced Adaptive Alert Explainability. The new **Why Did This Alert Trigger?** tab, available for both active and cleared adaptive alerts, provides clear insight into the system's decision-making process.

Key features:

* **View Alert Probability:** See how the system's confidence in an issue evolved over time and when it crossed your configured sensitivity threshold.
* **Compare Observed vs. Expected Anomalies:** A new graph shows the number of agents reporting anomalies compared to the system's learned baseline.
* **Visualize the Trigger Event:** Timelines highlight how metrics deviated from their expected behavior leading up to the alert.

This enhancement improves transparency by showing the data and logic behind each adaptive alert, helping you build trust in the system and take more informed action. For more information, see [Alerts](https://docs.thousandeyes.com/product-documentation/alerts).

### Improved Alerting Performance for Large-Scale Endpoint Agent Deployments

To improve alerting performance and reliability for large-scale Endpoint Agent tests, the Alert Details view and API will now display details for up to 500 violating agents per active alert.

Key changes:

* The Alert Details view and API now show details for a maximum of 500 agents per alert to ensure UI and API stability.
* The total number of violating agents is still displayed prominently, so you always know the full scope of an issue.
* This change prevents oversized alert payloads that could previously slow down processing when thousands of agents entered an alert state simultaneously.

This update ensures alert delivery stability and reduces load times, enhancing overall system resilience for your largest deployments. For more information about alerts, see [Alerts](https://docs.thousandeyes.com/product-documentation/alerts).

## 2025-11-03

### Mobile Endpoint Agent Android Version 1.30.0

The following enhancements have been made to the Mobile Endpoint Agent:

* Improved file sharing with a fallback option for Chrome OS and other devices that do not support default choosers.
* Added a mobile temperature profile feature.
* Mobile devices now support standard 1-minute tests running at 5-minute intervals, eliminating the need for separate mobile-specific tests.

## 2025-10-24

### Endpoint Agent Client Version 2.23.0

The following enhancements have been made to the Endpoint Agent client:

#### All Platforms

* The UDP path trace currently uses the UDP checksum to match ICMP replies. However, some middle boxes modify the checksum, causing incomplete path traces. To address this, we have modified the path trace to send UDP packets of varying sizes and correlate ICMP replies using the UDP packet length instead of the checksum.

## 2025-10-21

### Multi-Service View Support for Additional Test Types

We have added multi-service views support for the following test types:

* DNS Trace
* DNSSEC
* FTP
* SIP

This allows these tests to be stitched together in a single correlated view, helping users tell a more complete story across different protocol layers and vantage points during investigation. For more information about multi-service views, see [Multi-Service Views](https://docs.thousandeyes.com/product-documentation/tests/multi-service-views).

### New Cloud Agents

New Cloud Agents have been added in the locations listed below. For a full list of Cloud Agents, see [ThousandEyes Cloud Agent Locations](https://www.thousandeyes.com/product/cloud-agents).

* Kuwait City, Kuwait (Ooredoo)
* Lima, Peru (Movistar)
* Lima, Peru (Movistar) (IPv6)
* Macau, Macau (HK Telecom)
* Macau, Macau (HK Telecom) (IPv6)
* Mombasa, Kenya
* Mombasa, Kenya (IPv6)
* Sharjah, United Arab Emirates (Etisalat)

## 2025-10-15

### Test Button Now Available in Integrations 2.0

The **Test** button is now available for operations in the Integrations 2.0 experience. This feature lets you validate Custom Webhook operations before assigning them to alert rules.

* The **Test** button appears at the operation level, not on connectors.
* The **Test** button is also available in the Custom Webhook integration template.
* For operations without an associated connector, the button is visible but remains disabled.

This update replaces the temporary `Pending` status that was displayed for migrated Custom Webhooks and provides a more direct way to confirm configuration before deployment. For operations with a status of `Pending`, you will need to manually click the **Test** button to update the status.

For more information, including the earlier update where this was first announced, see [Integrations 2.0 Now Supports Custom Webhooks](https://docs.thousandeyes.com/whats-new/changelog#integrations-2.0-now-supports-custom-webhooks).

### Legacy Network and App Synthetics Test Creation Workflow Deprecation Notice

As [previously announced](https://docs.thousandeyes.com/whats-new/changelog#announcing-enhanced-test-creation-and-agent-selection), we are rolling out an updated and improved interface for creating Network and App Synthetics tests in ThousandEyes. After November 15th, 2025, all test types will be supported by the updated test creation workflow. At that time, all legacy test creation methods will be removed from the platform.

No action is required by you at this time.

## 2025-10-10

### Updates to Cloud Insights

#### Cloud Insights: Azure ExpressRoute Visualization

Cloud Insights now visualizes Azure ExpressRoute circuits in the path visualization and topology views for Network & App Synthetics tests.

For organizations with hybrid cloud environments, this provides end-to-end visibility into traffic from on-premises data centers to the Azure cloud. By mapping the ExpressRoute connection directly within the test's topology view, you can now monitor the performance and connectivity of these critical datacenter-to-cloud links. This enhancement helps you more effectively troubleshoot connectivity issues, validate network paths, and assure the performance of your hybrid Azure infrastructure. See [Dedicated Connections](https://docs.thousandeyes.com/product-documentation/cloud-insights/views#dedicated-connections) for more information.

#### Cloud Insights: Azure Integration Policies

You can now configure granular integration policies for Microsoft Azure, allowing you to select which resource types and subscriptions Cloud Insights monitors.

This update gives you precise control over the data Cloud Insights ingests from your Azure environment. The new **Integration Policies** page for Azure is divided into two sections:

* Enabled Resource Types: Select which types of Azure resources (such as Virtual WAN, ExpressRoute, or Security) to monitor. This helps you tailor data collection to your needs and avoid unnecessary permissions warnings for resources you don't intend to monitor.
* Subscription Rules: Define a set of ordered rules to include or exclude specific Azure subscriptions from monitoring based on their name or ID. Using Java regular expressions, you can create powerful policies, such as monitoring only production subscriptions or excluding all development environments, ensuring that you only ingest relevant inventory data.

For detailed instructions on configuring these policies, see the [Azure Integration Policies](https://docs.thousandeyes.com/product-documentation/cloud-insights/settings#azure-integration-policies) documentation.

#### Network & App Synthetics: New Cloud Insights Filter for Test Lists

A new filter is now available on the **Test Settings** page to quickly identify tests that are enriched with Cloud Insights data.

On the **Network & Application Synthetics > Views** page, you can now use the **Cloud Insights enriched tests** checkbox in the **Test** filter to narrow the test list. This makes it easier to manage and focus on tests that provide deep visibility into your cloud network topology. Selecting the filter shows only those tests that have been enriched with inventory data from your integrated AWS or Azure accounts, helping you isolate your cloud-endpoint tests from the rest. See [Filtering for Cloud Layer Tests](https://docs.thousandeyes.com/product-documentation/cloud-insights/views#filtering-for-cloud-layer-tests) for more information.

#### Network & App Synthetics: AWS Network and Security Layer Enhancements

In addition to the interfaces and security groups that make up the **Network and Security** topology in your **Network & App Synthetics > Views > Cloud** layer, we've added routing tables, transit gateway routing tables, subnets, and network access control lists (ACLs). These additions give you a significantly more detailed and granular view of the infrastructure that connects your cloud resources. See [Network and Security View](https://docs.thousandeyes.com/product-documentation/cloud-insights/views#network-and-security-view) for more information.

## 2025-10-09

### Cisco ThousandEyes Mobile Metrics on Dashboards (Android)

Mobile telemetry is now fully supported in Dashboards through the Mobile Endpoint Agent.

Supported metrics include:

* Cellular telephony and telemetry: Carrier name, RSSI, RSRP, RSRQ, SINR, network generation (3G, 4G, 5G, LTE), and network subtype (LTE, HSPA).
* Wireless and local network health: Wireless profile signal quality and throughput, local network profile link speed, and wireless signal quality.
* Scores: Device health score, connection health score (Wi-Fi and cellular), gateway health score, and memory.

Coming soon: Experience score, battery, temperature, and mobile template.

Not supported: CPU, retransmission rate, roaming or channel swap events, TCP protocol, and dynamic or real user tests.

{% hint style="info" %}
SINR data is available from September 19, 2025.
{% endhint %}

For more information on getting started, see the [Dashboard documentation](https://docs.thousandeyes.com/product-documentation/dashboards) and [sample dashboard](https://app.thousandeyes.com/share/dashboard/snapshots/?snapshotId=6d847e7c-29bb-47a7-bcbe-11b6225ad1bc\&teRegion=0\&menuId=dashboard).

### Cisco Application Hosting Framework (CAF) Version 5.1.2

CAF version 5.1.2 has now been released. This release is intended to replace the 5.1.1 image on all supported Cisco devices.

For upgrade instructions, see [Upgrading Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#cisco-application-hosting).

**New Features**

CAF 5.1.2 adds support for the `REPO_PROXY_*` environment variables available with our Docker Enterprise Agent. This will add more flexibility to the proxy configurations used by the agent and package manager.

For more information, see [Configuring an Enterprise Agent](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/proxy/configuring-an-enterprise-agent-to-use-a-proxy-server?q=APT_PROXY#configuring-proxy-settings-for-the-package-manager).

**Bug Fixes**

* An issue was found in CAF versions 5.0.1 and 5.1.1 where images would fail when being copied onto a Cisco Catalyst 9300 series switch, if the switch was running IOS XE 17.3.3. This was caused by unsupported PAX headers. The image format has been modified to be backwards compatible with earlier IOS XE software versions.
* An issue was found where agents running CAF version 5.1.1 on either ASR1k or ISR devices and configured as Traffic Insights forwarders may encounter failures. This was caused by the agent's inability to resolve "localhost", and has been fixed.

**MD5 Checksum Verification**

ThousandEyes recommends validating the checksum of downloaded packages. The md5 checksums for the CAF version 5.1.2 images are:

* f4cab9a36dd1e886df8eb76bbc80a0be thousandeyes-enterprise-agent-aarch64-5.1.2.cisco.tar
* e8145b92e77c7b88753fed406c9d5517 thousandeyes-enterprise-agent-x86\_64-5.1.2.cisco.tar

### Improvements in OAuth Token Configuration for Webhook Integration

You can now specify a scope parameter when setting up OAuth 2.0 Client Credentials authentication for custom webhook integrations. With this update, ThousandEyes custom webhooks can authenticate successfully using Microsoft Entra ID and other standards-compliant OAuth providers that require a scope parameter.

## 2025-10-07

### Views Explanations GA

Views explanations are now available for all users. You can leverage our integrated AI capabilities to help you quickly interpret and understand your Cloud and Enterprise Agent test results, and generate natural language summaries and fault domain analyses of test rounds. These explanations provide actionable insights into network and application performance across the following observed test layers:

* Page Load
* HTTP Server
* Agent to Server

For more information, see [AI Views Explanations](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/viewing-data#ai-views-explanations).

### Account Health Skill for the AI Assistant

The AI Assistant can review the health and operational hygiene of your environment, and provide a prioritized summary of issues, with clear recommendations for updates and changes.

You can ask the AI Assistant questions like:

* "Are any of my enterprise agents offline or overloaded?"
* “Do any of my enterprise agents have errors?

For more information about the AI Assistant, see [Cisco AI Assistant](https://docs.thousandeyes.com/product-documentation/getting-started/getting-support-from-thousandeyes#cisco-ai-assistant-integrated-in-thousandeyes).

### Login and Authentication Updates

#### Improved Login Experience for Locally Authenticated Organizations

We're excited to announce an important upgrade to the ThousandEyes login experience for organizations using local authentication (users who sign in directly at app.thousandeyes.com with a username and password, without using their organization's Identity Provider). Cisco is introducing a centralized authentication system to simplify access, enhance security, and provide a seamless single sign-on (SSO) experience across all Cisco products.

**What You Need to Know**

* **Automatic Migration Beginning the Week of October 20, 2025, Through Mid-November**: Your organization’s identity management will be migrated to the new Cisco Account during this period. You will continue to log in without disruption and no action is required.
* **Updated Password Expiration Policy**: For locally authenticated organizations, Cisco now enforces a default 5-year password expiration starting from the migration date. Organizations may optionally configure a 90-day expiration through organization-level settings in the ThousandEyes UI. SSO-enabled organizations are not impacted.
* **No action is required from you** for the automatic migration of your local-authentication users.

If your organization is currently using SSO, this migration will not impact you. We appreciate your attention and encourage you to stay tuned for future updates.

**Support**

If you or your users run into issues, see [Contacting Support](https://docs.thousandeyes.com/product-documentation/getting-started/getting-support-from-thousandeyes#contacting-support). For more information on our login experience, see [Logging In](https://docs.thousandeyes.com/product-documentation/user-management/authentication/logging-in).

#### Allow Network Traffic for Login and Access

To ensure uninterrupted login and access to the ThousandEyes platform and Cisco services, ensure that your network allows outbound traffic to the following domains:

* `https://idbroker*.webex.com/idb/**`
* `https://idbroker-static.webex.com/**`
* `https://*.cisco.com/**`

These domains are critical for authentication, as they delegate login processes to Webex and Cisco services. Blocking traffic to any of these domains may result in login failures or session interruptions.

## 2025-10-06

### Endpoint Agent Client Version 2.20.3

The following enhancements have been made to the Endpoint Agent client:

#### All Platforms

* In Zscaler version 4.6, the previous method for detecting VPN connections has been removed. A new, more effective method for monitoring VPN status has been introduced.

## 2025-10-02

### Dashboard Support for Event Detection

Event detection is now supported as a data-source for the following dashboard widgets:

* Color Grid
* Line Graph
* List
* Map
* Number
* Table

For more information, see [Event Detection](https://docs.thousandeyes.com/product-documentation/event-detection#dashboards) and [Dashboard Widgets](https://docs.thousandeyes.com/product-documentation/dashboards/dashboard-widgets).

## 2025-10-01

### New Agent Selector for Test Creation

The updated agent selector is now available for all users. The new selector provides you with a more refined and intuitive experience, allowing you to quickly build tests without searching through long lists of agents, gain a clearer picture of agent coverage and provider diversity, and fine tune your test deployment.

This update includes:

* **Geographical View:** View agents on a map to quickly identify coverage gaps and ensure the right regions are covered.
* **Enhanced Search:** Use the search bar and filters to quickly find the agents you want.
* **Labels Up Front:** Custom labels are brought to the foreground to ensure they are easy to access and filter by.
* **Better Provider Grouping**: Agents are now grouped more clearly by provider, making large lists simpler to navigate.
* **Advanced Mode**: Unlock deeper insights and agent metadata when you need them.

![Network Test Settings Basic Agent Selector](/files/vNww0s1NWoN8l89DcVVt)

![Network Test Settings Advanced Agent Selector](/files/ZxIzyuhgGlaZJ1x4RUYK)

## 2025-09-30

### Email Notification Support for Events

You can now configure email notifications for your Cloud and Enterprise Agent events using the standard alert notification configuration page. For detailed instructions, see [Alert Notifications](https://docs.thousandeyes.com/product-documentation/alerts/alert-notifications).

#### Removal of Existing Event Email Notifications

After January 5th, 2026, event email notifications created using previously available methods will be removed from the platform. You will need to create new email notifications using the alert notifications page to replace the existing ones.

### Dashboard Updates

* Groups in the color grid widget can now be sorted alphabetically or by value, in either an ascending or descending order.
* Widget descriptions now retain line breaks and formatting when displayed in the tooltip via the info icon. This ensures that descriptions appear consistently between the edit dialog and the tooltip, improving readability and alignment with the author’s intended format.

### Alert Updates

* The **Manage > Alert Rules > Network & App Synthetics** tab has been refreshed with minor UI improvements to streamline interactions.

## 2025-09-29

### Unattended Upgrade Reboot Schedule Configuration

You can now configure the preferred timing for when unattended upgrade reboots occur for ThousandEyes appliance agents. This feature enhances the security of customer environments while running Enterprise Agents and provides greater flexibility in operations by permitting upgrades during preferred maintenance windows.

For configuration instructions, see [ThousandEyes Virtual Appliance Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-virtual-appliance-installation).

### New BGP AS Path Pattern Alert

We are excited to introduce a new alert type for monitoring BGP Autonomous System (AS) path patterns. Using POSIX Regular Expression syntax, operators can define and enforce specific AS path patterns in prefix advertisements. This enables quick detection of unauthorized changes or inconsistencies in BGP routing, enhancing network security and reliability. Custom patterns can be configured for proactive monitoring and optimal network performance. For more details, see [AS Path Pattern Alert](https://docs.thousandeyes.com/product-documentation/alerts/creating-and-editing-alert-rules?q=as+path+length#as-path-pattern-alert).

### Endpoint Agent Client Version 2.20.2

The following enhancements have been made to the Endpoint Agent client:

#### All Platforms

* The agent now collects a packet capture (PCAP) by default when you run the network test function of the te-diagnostics executable and specify an output file.
* Updated VPN information extraction for Cisco AnyConnect to work regardless of system localization. The change is backward compatible with previous AnyConnect client versions.

#### Windows

* The Endpoint Agent now bundles NPCAP 1.83 or later, which uses a secure installer. For more information, see the [NPCAP Changelog](https://npcap.com/changelog).

#### macOS

* The agent now retrieves the user principal name on macOS using multiple identity provider services.

## 2025-09-26

### Extended Wi-Fi Details in Endpoint Agent Segment Visualization

Endpoint agents now offer enhanced insights into your Wi-Fi connection. In the Connection section of the Segment Visualization view and in the wireless node of the path visualization, you can view detailed information about the Wi-Fi network interface card (NIC) on Windows devices, including:

* NIC model: For example, Intel(R) Wi-Fi 6E AX211 160MHz
* NIC driver version: For example, 23.150.0.4

With this enhanced visibility, network and IT teams can quickly identify if performance issues are related to specific hardware models or outdated drivers. This streamlines root cause analysis and supports faster device troubleshooting.

#### How to access this information

In the Segment Visualization, expand the Connection segment to view NIC model and driver version details alongside existing Wi-Fi metrics. In Endpoint View, hover over a wireless node in the path visualization to see NIC model and driver version information.

This update is available for all supported Windows devices running the Endpoint Agent. We’re committed to providing actionable, transparent network insights to help you troubleshoot more efficiently.

## 2025-09-25

### Run Instant Test Permission

ThousandEyes has introduced a new permission called `Run instant tests` that allows you to run network and synthetics instant tests independently. This permission is distinct from the `Edit Test` permission, enabling more granular control.

{% hint style="info" %}
`Run instant tests` is not a part of any built-in roles. It is only available as part of a custom role.
{% endhint %}

## 2025-09-23

### SAML 2.0 Compliance Enforcement

We now strictly enforce [SAML (Security Assertion Markup Language) 2.0](https://www.cisco.com/site/us/en/learn/topics/security/what-is-saml.html) compliance for logins. Identity providers (IdPs) must return the `RelayState` parameter, which is used to direct you back to the correct page after authentication, exactly as sent by ThousandEyes (the service provider). If `RelayState` is modified or omitted, you may experience login failures or redirect loops.

## 2025-09-16

### Cisco ThousandEyes Mobile Endpoint Agent for Android

We are excited to announce the general availability of ThousandEyes Mobile Endpoint Agent v1.2.6 for Android. This update is now available on [Google Play](https://play.google.com/store/apps/details?id=com.thousandeyes.endpointagent\&hl=en) and supports Android 11 and later versions.

With this release, organizations can proactively monitor and troubleshoot device, network, and application performance. The agent can help reduce downtime and enhance user satisfaction by providing comprehensive visibility into devices, networks, mobile telephony, and telemetry data.

ThousandEyes Mobile Endpoint Agent is designed for enterprise-managed devices, including smartphones, tablets, Zebra barcode scanners, vehicle-mounted computers, point-of-sale systems and wearable devices.

#### Key Features

* **Scheduled Testing**: With near real-time insights into mobile network performance and application experience for faster issue resolution and analytics.
* **Platform Capabilities**: Scheduled ICMP and HTTP synthetic tests running in the background with support for Path Visualization, Views, Snapshots, Dashboards, Alerts, Device Health, Experience Score, and more.
* **Internet Connection Stability**: Gateway, Wireless Profile, Mobile Telephony and Mobile Telemetry (RSSI, RSRP, RSRQ, SINR)​ with insights into network generation (3G/4G/5G/LTE) and network subtype (LTE, HSPA).
* Deployment can be managed via industry-standard mobile device management (MDM) solutions such as Intune, Meraki Systems Manager, SOTI, Workspace ONE, and others.
* **Data Retention**: 14 days for Endpoint Essentials and 30 days for Advantage licenses.
* Future releases will include support for ChromeOS and Honeywell scanners

{% hint style="info" %}
CPU metrics, TCP protocol, dynamic tests, real user tests and Wireless Metrics (Retransmission Rate, Roaming Events & Channel Swap Events) are not supported on mobile devices. The minimum test interval is 5 minutes, with a maximum of 4 concurrent tests.
{% endhint %}

The following resources will help you get started:

* [Mobile Endpoint Agent Announcement Blog](http://blog.thousandeyes.com/assuring-your-mobile-enabled-business)
* Documentation: [Mobile Endpoint Agent Installation on Android Devices](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/installing/mepa_android)
* [Solutions Page](https://www.thousandeyes.com/solutions/assurance-for-mobile-business)
* [Meraki SM Guide](https://youtu.be/FP6Y9I5mGKY)

### Important Notice on Cookies for Login and Access

As we simplify the login experience over the coming months, you may be directed to a Cisco login page to access the ThousandEyes platform and other Cisco services. To ensure a seamless and secure login process, it is essential that your browser allows cookies from the following domains:

* webex.com
* cisco.com
* thousandeyes.com

These cookies are necessary to:

* Maintain your login session securely.
* Enable core functionality and personalized settings.
* Support authentication flows and access to collaboration tools.
* Provide enhanced performance and troubleshooting capabilities.

Blocking or disabling cookies from these domains may result in login issues, interrupted sessions, or degraded user experience.

## 2025-09-15

### Updated Settings for Page load, Transaction, and API Tests

We've updated the settings page for page load, transaction and API tests with an improved user interface. This provides a more intuitive experience, aligning these test types with our [enhanced test creation](https://docs.thousandeyes.com/whats-new/changelog#announcing-enhanced-test-creation-and-agent-selection).

Key features:

* Faster, Clearer Configuration: The refreshed design clarifies the setup process, allowing you to deploy tests more quickly.
* Seamless Agent Selection: Find and assign the right agents for your test faster with powerful search and filtering by location, label, and network.

For more information, see the documentation for [Web Layer Tests](https://docs.thousandeyes.com/product-documentation/tests/web-layer-tests).

## 2025-09-11

### Removing Duplicate Devices

To enhance our device monitoring efficiency, we are revising our device discovery process to eliminate duplicated devices identified through multiple scans. This change will take effect after December 10th, 2025.

After December 10th, we will perform a one-time cleanup of all monitored and unmonitored duplicate devices. Duplicates will be identified as devices sharing the same IP address, agent, MAC address, and engine ID, and will be automatically removed.

**Unmonitored Duplicates**

For unmonitored devices, we do not anticipate any interruptions to your experience, as these devices do not monitor or report data to the platform. However, if you have a scheduled discovery that includes these devices, they may reappear in your environment after the cleanup.

**Monitored Duplicates**

For monitored duplicates, the primary device will continue to be monitored and will continue reporting data to the platform.

{% hint style="warning" %}
The historical data of any duplicate devices removed will be lost, and any alerts triggered by them will be automatically closed.
{% endhint %}

If you have any questions, contact ThousandEyes Support.

## 2025-09-04

### New Easy Onboarding: Automated BGP Prefix Discovery and Monitoring

Easy Onboarding automates BGP prefix discovery and alert setup. Enter an Autonomous System (AS) number to automatically discover associated prefixes and apply best-practice alerts. You can review, customize, and confirm your monitoring configuration in just a few steps.

**Key benefits**:

* Monitor up to 500 prefixes automatically
* Save time by removing manual setup
* Improve routing visibility and security

Existing customers can also use Easy Onboarding to add additional prefixes for an AS, with the option to choose traditional or automated methods. Future updates will include proactive monitoring for AS changes.

For setup instructions, see [BGP Easy Onboarding](https://docs.thousandeyes.com/product-documentation/tests/bgp-tests/bgp-easy-onboarding).

## 2025-09-03

### Integrations 2.0 Now Supports Custom Webhooks

Custom Webhooks are now fully available in the [Integrations 2.0 experience](https://docs.thousandeyes.com/product-documentation/integration-guides). Existing configurations have been migrated automatically, including payload templates, headers, authentication, and variable mappings. Alert delivery behavior is unchanged.

Integrations 2.0 introduces a new permission model. Two new permissions control access across both Connectors and Operations: `INTEGRATIONS ALL READ` (read access to all Connectors and Operations) and `INTEGRATIONS ALL UPDATE` (create, update, and delete all Connectors and Operations, and assign Operations to Connectors). The v7 API and the Integrations 2.0 UI enforce these permissions. Individual Connector and Operation types may require additional permissions.

As a one-time update, we mapped existing Alert Rules permissions to the new Integrations permissions. Any role with `EDIT ALERT RULES` received `INTEGRATIONS ALL UPDATE`, and any role with `VIEW ALERT RULES` received `INTEGRATIONS ALL READ`. Going forward, you can create roles with Alert Rules permissions without granting Integrations permissions; in that case, users will continue to see Integrations 1.0 data with minimal fields on the **Alert Rules** page and can keep assigning integrations to alert rules, but they won’t be able to manage items in Integrations 2.0.

Note: You may temporarily see a *Pending* connection status in the **Operations** tab for Custom Webhooks after migration. This is expected and will be updated once the **Test** function is introduced in the next couple of weeks. The *Pending* state does not affect your ability to receive alert notifications. If the integration worked in 1.0, it will continue to work in 2.0 regardless of its *Pending* status.

### Recorder IDE v1.24.0

Recorder IDE v1.24.0 has now been released:

* Updated the Windows installation to allow customers to change the installation directory.

{% hint style="info" %}
To utilize this functionality, you will need to uninstall the recorder, then reinstall the latest version. This is because the new functionality is part of the installation wizard, which is not triggered when upgrading.
{% endhint %}

## 2025-09-02

### API Token Expiration Notification

To prevent unexpected service disruptions caused by expired API bearer tokens, ThousandEyes will now send proactive email notifications to users.

**Key features:**

* Notifications sent twice monthly when tokens are within 10 weeks of expiration.
* Emails include expiration details and renewal instructions.
* No notifications are sent if tokens are renewed or deleted before the alert window.

This feature helps maintain seamless API access with minimal user intervention.

## 2025-08-27

### API Test Support for OpenTelemetry Traces

ThousandEyes for OpenTelemetry now supports API tests in the traces data model v2. You can now export trace data from API tests alongside page load and transaction tests, providing comprehensive visibility into API performance and behavior.

**Key features:**

* Full support for API test traces.
* API-specific span attributes, including the `step` attribute for multi-step API test sequences.

For more information, see [ThousandEyes for OpenTelemetry Data Model v2 - Traces](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/data-model/data-model-v2/traces).

## 2025-08-26

### UDP Support for Endpoint Agent Dynamic Tests

Dynamic tests running on Endpoint Agent version 2.13.1 or higher now support the User Datagram Protocol (UDP), in addition to TCP and ICMP, to better reflect real-world network traffic. Webex and Microsoft Teams tests now use UDP by default. Each UDP-based dynamic test provides a detailed path trace with UDP traffic. These updates help ensure more accurate and relevant results. We're aware that some UDP tests for Microsoft Teams may report failed path traces, even when end-to-end measurements succeed. We'll provide updates as improvements are made.

### Recorder IDE v1.23.0

Recorder IDE v1.23.0 has now been released:

* Resolved a breaking change in the prior version that prevented users from replaying recordings.

{% hint style="warning" %}
Please ensure that you are using the latest version of the recorder IDE as soon as possible to ensure the software works as expected.

Versions prior to v1.21.0 use the ThousandEyes v6 APIs, which are no longer supported (see [ThousandEyes API v6 End of Life Reminder](https://docs.thousandeyes.com/whats-new/changelog#thousandeyes-api-v6-end-of-life-reminder).
{% endhint %}

## 2025-08-25

### Stream ThousandEyes Activity Logs with ThousandEyes for OpenTelemetry

You can now stream user activity logs from ThousandEyes using the ThousandEyes for OpenTelemetry integration. Logs are now supported as a third signal, allowing you to monitor user activity alongside metrics and traces for unified observability and deeper insight into service behavior.

For more information, including supported log types and schema, see [ThousandEyes for OpenTelemetry data model – Logs](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/data-model/data-model-v2/logs).

## 2025-08-22

### Recorder IDE v1.21.0

Recorder IDE v1.21.0 has now been released:

* Existing functionality has been upgraded to use ThousandEyes v7 APIs.
* Login and authentication now use OAuth 2.0.

{% hint style="warning" %}
Please ensure that you are using the latest version of the recorder IDE as soon as possible to ensure the software works as expected.

Versions prior to v1.21.0 use the ThousandEyes v6 APIs, which are no longer supported (see [ThousandEyes API v6 End of Life Reminder](https://docs.thousandeyes.com/whats-new/changelog#thousandeyes-api-v6-end-of-life-reminder).
{% endhint %}

## 2025-08-21

### New Multi-Chart Capability in Cloud Insights Views

Cloud Insights Views has been enhanced with multi-chart capability that enables you to view up to three traffic charts at the same time. This helps you identify related traffic pattern changes. Find more information at [Cloud Insights Views](https://docs.thousandeyes.com/product-documentation/cloud-insights/views).

## 2025-08-14

### Meraki OAuth 2.0 Integration

ThousandEyes now supports integrating Meraki using OAuth 2.0. This allows you to grant Meraki limited, token-based access to your ThousandEyes data — only for the data and actions you authorize. For more information on what information is exchanged with Meraki, see [OAuth 2.0 with ThousandEyes](https://docs.thousandeyes.com/product-documentation/user-management/authorization/oauth-overview).

### New Integration with Splunk IT Service Intelligence (ITSI)

We are excited to announce a new integration between ThousandEyes and Splunk IT Service Intelligence (ITSI). This integration enhances your end-to-end service monitoring by bringing Splunk context directly into ThousandEyes test results.

**Key benefits:**

With this integration, you can:

* Visualize Splunk ITSI episodes in ThousandEyes: View Splunk incidents alongside Cloud and Enterprise Agent test results, directly within the ThousandEyes app.
* Correlate incidents in real time: Hover over the test timeline to see both ThousandEyes metrics and any associated Splunk ITSI episodes at a specific point in time.
* Access detailed episode insights: A new **Splunk ITSI** tab on affected test result pages displays each episode’s title, duration, description, and severity, imported directly from Splunk.
* Pivot to Splunk with one click: Each episode includes a link to the full incident details in your Splunk ITSI environment.

This integration is available to all ThousandEyes customers who also use Splunk ITSI. For setup requirements and configuration instructions, see the [Splunk ITSI integration guide](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-built-integrations/splunk-app/itsi).

## 2025-08-13

### New Cisco Device Support for Enterprise Agents

ThousandEyes is dedicated to providing last-mile visibility and performance across the edge network. With the release of Cisco IOS XE 17.18.1, ThousandEyes now supports the installation of Enterprise Agents on the following Cisco platforms, using the Application Hosting Framework image version 5.1.1 or later:

* Cisco C9350 series smart switches
* Cisco C8000 series secure routers
* Cisco Industrial Ethernet switches
* Cisco Industrial Routers

For a detailed list of supported devices and system requirements, refer to the relevant support matrix documentation under [Cisco Devices](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices).

### New Linux Distribution Support

ThousandEyes now supports the installation of Enterprise Agents on the following Linux distributions:

* Ubuntu 24.04 LTS (“Noble Numbat”)
* AlmaLinux 8.x and 9.x
* Amazon Linux 2023

For support dates, refer to the [Enterprise Agent Support Lifecycle](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/enterprise-agent-support-lifecycle), and for installation instructions, refer to the [Linux Package Agent Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/linux-package-agent-installation) documentation.

### aarch64 Architecture Support for Enterprise Agents

ThousandEyes Enterprise Agents can now be installed on both *x86\_64* and *aarch64* architecture hosts for any supported Ubuntu operating system.

In addition, the Docker agent can now run on *aarch64* architecture by automatically selecting the appropriate image based on the host architecture.

{% hint style="info" %}
BrowserBot is only supported on x86\_64 architecture images.
{% endhint %}

For detailed Docker installation instructions, see [Docker-Based Agent Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/docker-based-agent-installation).

### Restriction of Unsupported Linux Versions

As [previously announced](https://docs.thousandeyes.com/whats-new/changelog#rocky-linux-9.4-end-of-life-and-restriction-of-unsupported-linux-versions), we have now restricted the use of any ThousandEyes Enterprise Agent running on unsupported Linux operating systems.

For a list of supported Linux operating systems, see [Supported Enterprise Agent Operating Systems](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents#supported-enterprise-agent-operating-systems).

### ThousandEyes API v6 End-of-Life Reminder

Support for ThousandEyes API v6 ended on May 27, 2025. All API v6 operations will be decommissioned after May 27, 2026. After this date, any integration or workflow that relies on API v6 will stop working.

#### Why migrate now?

* ThousandEyes API v7 is the only version supported by the latest tools and software development kits (SDKs), including the Terraform Provider version 3, [ThousandEyes Java SDK](https://github.com/thousandeyes/thousandeyes-sdk-java), and [Python SDK](https://github.com/thousandeyes/thousandeyes-sdk-python).
* API v7 continues to expand with new operations, improved standardization, and enhanced performance.
* Migrating early ensures a smoother transition and access to support and resources.

**Note:** Migration should be done using only the [documented API v7 operations](https://developer.cisco.com/docs/thousandeyes/v7/). Using undocumented or preview API operations, such as those that appear to work after a v6 to v7 substitution, may result in broken workflows after full deprecation. These operations are not guaranteed to be stable or supported.

To help with migration, we’ve prepared the [API v7 Migration Guide](https://developer.cisco.com/docs/thousandeyes/v7/migration-guide-overview/).

We strongly recommend completing your migration to API v7 as soon as possible to avoid service disruptions.

### Endpoint Agent Client Version 2.17.1

The following enhancements have been made to the Endpoint Agent client:

#### All Platforms

* Resolved an issue from version 2.13.1 that caused the agent to crash when collecting Wi-Fi interface metrics if the operating system did not provide the PHY mode.
* Fixed an issue where the diagnostics bundle reports an incorrect system architecture.
* Extend support for Cisco ZTA to include scenarios where TIA is used.

#### Windows

* The agent now provides comprehensive Wi-Fi event tracking, irrespective of the device's Location Services status. Previously, no Wi-Fi events were tracked if the location services were disabled.
* Resolved an issue where diagnostic bundles might not be created if certain Unicode characters are present in the file path.

## 2025-08-12

### API Token Management API Now Available

We have introduced a new **API Token Management API** that enables customers to programmatically regenerate their ThousandEyes user bearer tokens. This enhancement removes the previous limitation of UI-only token management which requires manual intervention. With the API, customers can enhance automation workflows and reduce operational inefficiencies in machine-to-machine integrations.

**Highlights:**

* Both the old and new tokens remain valid for a 14-day grace period, allowing for a seamless transition.
* Token regeneration is restricted to the token’s owner.
* The existing UI functionality remains unchanged.

For more information, see the [API documentation](https://developer.cisco.com/docs/thousandeyes/v7/regenerate-api-token/).

## 2025-08-06

### Improved Tag Attribute Handling with Advance Enforcement Notice for OpenTelemetry Streams

As part of ongoing improvements to OpenTelemetry (OTel) integration, ThousandEyes has released a temporary update to how non-compliant tags are handled in streamed telemetry data.

#### What’s Changing (Effective Immediately)

* Tags that do not conform to the [OpenTelemetry naming recommendations for attributes](https://opentelemetry.io/docs/specs/semconv/general/naming/#recommendations-for-application-developers) (for example, containing spaces or invalid characters) will continue to be included in telemetry streams only if they are referenced in a stream’s `tagMatch` configuration.
* All other non-compliant attributes will be dropped from the streamed data.

This change is intended to preserve compatibility with existing integrations during the transition period.

#### Upcoming Breaking Change (Effective September 2025)

Starting in September 2025, ThousandEyes will enforce full compliance with OpenTelemetry attribute naming requirements.

* All non-compliant tags, including those used in `tagMatch`, will be dropped from telemetry streams.
* Any associated test data (metrics and traces) containing invalid attributes will be excluded entirely from the stream.
* For all metric and trace datapoints, only valid tags will be included in the attributes. Invalid attributes from agents or tests will be removed.

#### Action Required

To avoid data loss and ensure continued compatibility, update your tags to meet the [OpenTelemetry naming recommendations for attributes](https://opentelemetry.io/docs/specs/semconv/general/naming/#recommendations-for-application-developers) as soon as possible.

## 2025-08-05

### Cookie Consent Manager Added to ThousandEyes App

To support compliance with new EU data policy regulations and align with other Cisco products, we have introduced a Cookie Consent Manager to app.thousandeyes.com. This update provides users with greater transparency and control over cookie usage within the ThousandEyes application.

* Scope: A new Cookie Consent Manager is now present on app.thousandeyes.com. The cookie consent manager already in place on the ThousandEyes marketing site is unchanged for the time being.
* Purpose: This change was implemented in response to evolving data privacy regulations and at the request of our Legal team.
* User Impact: Upon login, users will be prompted to review and manage their cookie preferences.

## 2025-08-04

### New ThousandEyes Login Experience

The enhanced [ThousandEyes login experience](https://docs.thousandeyes.com/product-documentation/user-management/authentication/logging-in) is now live. This update simplifies the login process and improves account security.

What's New:

* Automated Detection – After you enter your email address, ThousandEyes automatically detects your authentication method based on your user permissions and organization settings. You no longer need to manually select Single Sign-On (SSO).
* Enhanced Security – The "Keep me logged in" option has been removed to strengthen account security.
* Updated SSO Behavior – Login behavior now adapts to your organization’s SSO configuration and user permissions. Depending on your default organization settings, you may be redirected automatically to your identity provider (IdP) or given the option to choose between SSO and local login.

  For a detailed breakdown of login behavior, see [Login Behavior by Organization SSO Configuration and User Permissions](https://docs.thousandeyes.com/product-documentation/user-management/authentication/logging-in#login-behavior-by-organization-sso-configuration-and-user-permissions).

## Archived Changelog Entries

{% hint style="info" %}
The ThousandEyes changelog contains the last three to six months of entries. Older entries can be found in the [Archived Release Notes](https://docs.thousandeyes.com/archived-release-notes).
{% endhint %}


# Getting Started

Welcome to ThousandEyes, a network intelligence SaaS platform that provides you with real-time visibility into Internet-enabled applications and networks. You can easily set up tests using global vantage points or by hosting agents within your infrastructure to monitor services like DNS resolution, browser response characteristics, detailed aspects of network pathing and connectivity, the status of network routing, and VoIP streaming connection quality.

We're excited to have you join our community of network intelligence experts, and these getting started guides will help you quickly ramp up on our platform. Use the starter exercise below to get logged in so you can begin your journey. Whether you're new to proactive monitoring or a seasoned network pro, our team is here to support you every step of the way.

## Prerequisites

This exercise requires a ThousandEyes account. If you have a user account, but do not have the required permissions, you can reach out to your ThousandEyes admin user for assistance. If you do not know who your ThousandEyes admin is, reach out to support by following the guide in the [Support](#support) section below. If you don't have a user account, or if you are unable to add test creation permissions to your existing account, you can create a trial account here: [Sign up for a ThousandEyes Trial](https://www.thousandeyes.com/signup).

### Supported Browsers

To log in to the ThousandEyes platform <https://app.thousandeyes.com> users must be running the most recent version of one of the following browsers (desktop or mobile versions) :

* Google Chrome
* Mozilla Firefox
* Apple Safari
* Microsoft Edge

Attempting to log in using a different browser (as determined by the User-Agent string) will result in redirection to <https://app.thousandeyes.com/bad-browser>, which will display an error message.

## Exercise: Log in to the ThousandEyes Application

To get started, navigate to [https://app.thousandeyes.com/](https://app.thousandeyes.com) in a web browser, and log in using your user credentials.

## Getting Started Guides

{% hint style="info" %}
These guides will be super helpful in getting you started with ThousandEyes. If you have any questions or need further assistance, please don't hesitate to reach out to our support team.
{% endhint %}

### Account Setup and Account Groups

Learn how to set up your ThousandEyes account to align with your teams, integrate with SSO, track usage and view account activity.

[Getting Started with Account Setup](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-account-setup)

### Network & App Synthetics

Learn how ThousandEyes Network & App Synthetics can be configured to provide an "outside-in", "inside-out", or "inside-in" vantage point for insights into the performance and dependencies of your critical applications and network related services.

[Getting Started with Network & App Synthetics](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-cloud-and-enterprise-agents)

### Network & App Synthetics Tests

Learn how to configure ThousandEyes tests to provide visibility into your critical network infrastructure and business services. Learn how to create a basic test and interpret the data so you can quickly mitigate service disruptions and answer the age old question: Is it the network or the application and where is the problem?

[Getting Started with Network & App Synthetics Tests](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-cloud-and-enterprise-agent-tests)

### Endpoint Agents

Learn how ThousandEyes end-user monitoring can be used for visibility into employee’s experience of SaaS and internally-hosted applications in context with the underlying wireless LAN, WAN, Internet connectivity and system health. Automatically monitor network connectivity for dynamic applications like Webex, Microsoft Teams and Zoom using ThousandEyes automated session tests.

[Getting Started with Endpoint Agents](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-endpoint-agents)

### Device Agents

Learn how you can test to the last mile of the internet - end-users' home routers and mobile apps. Device Agents can be embedded on routers or within mobile apps to enable tests for speed and latency as well as users' experience of applications from games to social media sites to streaming services. Finally, you can understand what's happening beyond where your network ends.

[Connected Devices](https://docs.thousandeyes.com/product-documentation/connected-devices)

### Transaction Tests

ThousandEyes transaction tests can be configured to mimic user actions or API sequences. Transaction tests provide deep insight into the user experience enabling you to ensure that the user journey completes successfully or in the event that a problem occurs quickly isolate if it’s an application or network issue.

[Getting Started with Transactions](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-transactions)

### Dashboards

ThousandEyes dashboards are a powerful tool to help visualize your application and network health and help proactively find issues. Learn how to create a dashboard using widgets to show your key metrics and provide your teams with visibility into the metrics that matter.

[Getting Started with Dashboards](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-dashboards)

### Alerts

Learn how to transform your ThousandEyes environment from reactive to proactive and integrate alert notifications into your workflow using email or webhooks for third party systems.

[Getting Started with Alerts](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-alerts)

### Internet Insights and Application Outages

Learn how ThousandEyes can enable operations teams with visibility into larger network and application provider outages. ThousandEyes Internet Insights and Application Outages algorithmically leverages our massive data set to help teams with the global, regional or service related outage perspective so they can remediate issues.

[Internet Insights](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-internet-insights)

### ThousandEyes API

Explore the basics of using the ThousandEyes API and how to programmatically use the RESTful API. There are many different API endpoints that can be used to automate administration tasks, extract test data and integrate into your workflow. This guide includes examples using cli tools, python and node.js to help you on your journey.

[Getting Started with the ThousandEyes API](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-the-thousandeyes-api)

### Support

Find out more about how customers can contact the ThousandEyes Customer Engineering team 24 hours a day, 7 days a week through email, chat app and via the web using our support portal. Customer Engineering provides technical support to customers who have an account for the ThousandEyes application.

[Getting Support from ThousandEyes](https://docs.thousandeyes.com/product-documentation/getting-started/getting-support-from-thousandeyes)

### ThousandEyes FAQ

Review our new user FAQ for more information.

[New User FAQ](https://docs.thousandeyes.com/product-documentation/getting-started/new-user-faq)


# Getting Started with Account Setup

This section helps you learn about configuring your account as an administrator, securing user access, and planning usage - as well as tracking account activities.

## Account Setup Steps

1. [Using Account Groups](#using-account-groups)
2. [Securing User Access](#securing-user-access)
3. [Enabling Single Sign-On](#enabling-single-sign-on)
4. [Tracking License Usage](#tracking-license-usage)
5. [Auditing Account Activity](#auditing-account-activity)

## Using Account Groups

Every ThousandEyes user belongs to an *organization*, which represents the customer's billing entity. Any licenses you purchase apply to your entire organization and are shared by account groups. An *account group* is an entity internal to your organization that divides it into functional groups. For detailed information about account groups, see [What Is an Account Group](https://docs.thousandeyes.com/product-documentation/user-management/account-groups/what-is-an-account-group).

Account groups divide users, tests, agents, dashboards, alert rules, and many other elements of the ThousandEyes platform. Account groups are a way to create an independent instance within an organization, for security or functional purposes.

For example, Organization A can be divided into account groups for IT, NetOps, and DevOps. Each department uses the ThousandEyes platform within their own account group. While billing is shared, the users in one account group cannot access other account groups' data (unless it is specifically shared across account groups).

A user can belong to multiple account groups and can switch between them without re-authentication. In the example below, "Super User" has access to two account groups in the "ThousandEyes Demos" organization, and is currently logged into the “ThousandEyes Demos” account group:

![a user named Super User is a member of two account groups](/files/8rrmFhmNg9Be4fhBnmPS)

It's best to plan in advance how you will use account groups based on your corporate structure. There is no limit on the number of account groups you can add.

To create account groups in the ThousandEyes platform, go to **Manage > Account Settings > Users and Roles > Account Groups**.

## Securing User Access

When you add new users to the platform, you must assign each one to an account group and a *role*. The ThousandEyes platform provides a [role-based access control (RBAC) model](https://docs.thousandeyes.com/product-documentation/user-management/rbac/role-based-access-control-explained), in which users' roles determine what they can do within the platform. The administrator can opt for the default, built-in roles, or can create custom roles.

![assigning a user to a role](/files/MOEexPngmA9uKQsCHsEj)

The built-in roles are Organization Admin, Account Admin, and Regular User:

* The Organization Admin role has full permissions including managing usage, users, and account groups. We suggest reserving this role for a limited number of administrators who are fully trained in ThousandEyes account setup.
* The Regular User role is for read-only-access users, and carries no administrative permissions.
* Users who need an access level between Organization Admin and Regular User can hold the Account Admin role.

For detailed information on these built-in roles, see [Built-In Roles](https://docs.thousandeyes.com/product-documentation/user-management/rbac/role-based-access-control-explained#built-in-roles).

Alternatively, you can build a custom role by selecting the desired [permissions sets](https://docs.thousandeyes.com/product-documentation/user-management/rbac/built-in-roles-and-permissions).

### Creating a Custom Role

{% hint style="info" %}
To create a custom role, you must have the *Edit roles* permission.
{% endhint %}

When you create a new role, you can use it in any account group within the organization. While users with the Organization Admin role automatically have access to all account groups, non-Organization Admin users must be assigned a role for each account group they belong to.

To create a custom role, go to **Manage > Account Settings > Users and Roles > Roles**. Keep in mind the following guidelines:

* Follow the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) and limit the user's access to only the specific functions they need to perform their job.
* Reserve [management permissions](https://docs.thousandeyes.com/product-documentation/user-management/rbac/role-based-access-control-explained#management-permissions) for administrators only.

  ![list of management permissions](/files/SD54SuWlarwY0g5N93I4)
* Make sure every user can view [public snapshots](https://docs.thousandeyes.com/product-documentation/dashboards/dashboard-shares-snapshots) for collaboration.

  ![permissions for public snapshots](/files/yuGAmaeyPcUU4Cfh1Gfy)
* If you plan to use [SSO](https://docs.thousandeyes.com/product-documentation/user-management/sso), the **Login via Single Sign-On** permission is required.

  ![permissions for SSO](/files/JBE7pbUq7e93Gqc2MJWa)
* Consider who should view or edit the [credentials repository](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/getting-started/working-with-secure-credentials#managing-credentials-in-the-credentials-repository).

  ![permissions for credentials-repo access](/files/ndZfWn6U0ROgNLSzsPAq)
* If you plan to create or use [integrations](https://docs.thousandeyes.com/product-documentation/integration-guides), including [custom webhooks](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-webhooks), the accounts for those services must have API access.

  ![permissions for API access](/files/wV7jQeePUOEQhNsT2SkR)

## Enabling Single Sign-On

Reducing login to one set of credentials improves enterprise security. ThousandEyes supports SAML 2.0-based single sign-on (SSO) so you can follow your organization's security policies. Before you invest time in manually provisioning new users, we suggest that you check whether your directory service supports SAML 2.0 and SCIM provisioning.

In addition, with any identity provider (IdP) that supports System for Cross-domain Identity Management (SCIM) provisioning, user accounts can be auto-provisioned via your IdP. Manually provisioning and deprovisioning user accounts for every SaaS application costs your IT team enormous time and effort. A common security issue is terminated users who can continue to use a SaaS application using the same password. You can avoid these issues by using SCIM auto-deprovisioning users' accounts when their access is removed from the IdP. In addition, ThousandEyes will automatically benefit from enhanced security, like multifactor authentication (MFA) that the IdP provides.

We highly recommend you consider enabling (or forcing, for added security) SSO before onboarding any users. To make setup easier, we provide [ThousandEyes-side configuration instructions](https://docs.thousandeyes.com/product-documentation/user-management/sso/how-to-configure-single-sign-on-with-metadata) for the major IdPs, listed below, as well as an overview and links to their IdP-side configuration instructions:

* Duo
* Microsoft Azure Active Directory
* Microsoft Active Directory Federation Services
* PingOne
* Okta
* Google Workspace
* OneLogin
* miniOrange

If your system supports loading XML metadata, we recommend using ThousandEyes metadata, which can be downloaded from <https://app.thousandeyes.com/saml-metadata> for your service provider configuration. For IdP configuration, we support static configuration, metadata import, as well as dynamic configuration that parses the IdP’s public URL.

To start setting up SSO, go to **Manage > Account Settings > Organization Settings > Security and Authentication**.

{% hint style="warning" %}
Before you save your SSO configuration, use the **Run Single Sign-On Test** button to test it. Make sure the test passes before you save the configuration; otherwise, it will impact existing users' ability to log in.
{% endhint %}

![screen for setting up SSO](/files/BcaeKf4zxaMZVrfylSzE)

## Tracking License Usage

ThousandEyes customers commit to an annual contract that can include the following forms of subscription:

* Units for Cloud and Enterprise Agent tests
* Endpoint Agent licenses
* Internet Insights packages

You can view your subscriptions at **Manage > Account Settings > Usage and Billing**.

The **Plan Usage** section shows your monthly subscription status, including:

* Billing period (the date when monthly usage is reset)
* Usage included in your plan
* Units and licenses used to date
* For units, the projected usage by the end of the billing cycle

![Plan usage tab showing units used and projected](/files/otGaUNsmXczLp2NsAk6q)

In the above customer’s example, their billing cycle begins on the 14th of every month, and their usage is not exceeding the limit at this point, especially for units. As unused units do not roll over from month to month, we would suggest that this customer should add tests to consume more units.

Units are calculated based on the test's type, interval, and timeout, and on the number and type of ThousandEyes agents running the test. As a SaaS solution, ThousandEyes provides a usage-based consumption model, which means that every running test uses units.

You can break usage down by account group, test type, or individual test. The **Used** versus **Projected** labels can provide easy guidance about which account group, test type, or individual test consumes the most units, and whether your current usage will exceed the set limit by the end of the billing cycle.

For details on usage-based consumption, see [About Our Consumption Model](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/about-our-consumption-model).

![Example of Cloud Agent unit usage table, broken down by tests](/files/EJlv2KVe72LC7ehrL2jS)

### Keeping Usage Under 100%

{% hint style="info" %}
**Overages**: This section does not apply to customers who have overages enabled. For more information about overages, see [Overages](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/about-usage-units#overages).
{% endhint %}

As ThousandEyes admins, you aim to keep your organization's usage below the monthly allowance. ThousandEyes offers three ways to help you prevent overages:

* Use the calculator to estimate unit consumption. The [ThousandEyes calculator](https://app.thousandeyes.com/calculator/) automatically pulls your organization's current test settings and calculates the monthly total. It allows you to overwrite tests' interval, timeout, number of agents, and the number of tests as you calculate usage.

  To avoid unexpected unit consumption, we highly recommend you run the calculator when you change existing test settings or create new tests.

  For more information about using the calculator, see [Calculating Units](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/calculating-units).
* Set a usage quota on account groups. For every account group, you can set a usage quota to guard against unwanted overages. Quotas can be set by percent of your total plan or by number of units.

  To create a usage quota, go to **Manage > Account Settings > Usage and Billing > Quotas**.

  ![screen for creating usage quotas](/files/FeYXtM4yqpLVBuPrrnBE)

  When the projected units in the current billing cycle exceed the quota, users see a warning message and are prevented from saving test configurations that consume more units. For times when you need to run more tests, we recommend you expand your unit capacity.

  For more information about setting quotas, see [Setting Quotas](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/setting-quotas).
* Set up usage alerts.

  You can configure alert rules so that you receive a notification when your organization's projected or actual usage exceeds certain levels. For detailed information about usage alerting, see [What happens if my organization exceeds our monthly quota?](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/usage-faqs#what-happens-if-my-organization-is-projected-to-exceed-our-monthly-quota-of-units).

To remain within your contracted usage, we recommend the following:

* Make sure your test's intervals, agents, and timeouts match your business needs.
* Don’t add use cases without also adding adding capacity.
* Use the calculator before making changes.

## Auditing Account Activity

ThousandEyes offers a live platform shared by multiple concurrent users. There is no version-control method that allows administrators to revert a user's configuration changes to a previous point in time. Every save action is final, so should be made with due consideration.

Instead, we offer the [activity log](https://docs.thousandeyes.com/product-documentation/user-management/user-activity/working-with-the-activity-log) that exposes UI actions made by all users. For each action, the log provides details of the account group, user, component, and a description. You can download the logs for up to two years' activity, for audit purposes.

In addition to its uses for transaction details, you can use the activity log to measure the adoption of the ThousandEyes platform in your organization. For example, the activity log shows which users you have added to the platform have then activated their accounts. To view the activity log, go to **Manage > Account Settings > Activity Log**. For detailed information, see [Working with the Activity Log](https://docs.thousandeyes.com/product-documentation/user-management/user-activity/working-with-the-activity-log).

![activity log](/files/2xOaUypCiTkux9u4qDb0)


# Getting Started with Cloud and Enterprise Agents

ThousandEyes Cloud and Enterprise Agents provide you with an "outside-in", "inside-out" or "inside-in" vantage point for insights into the performance and dependencies of your application, regardless of how the application is delivered (internal to your datacenter, as SAAS, or from a third-party datacenter).

This article helps you get started with using Cloud Agents and deploying Enterprise Agents to your environment.

## Prerequisites

For this guide, we assume you have read the previous getting-started guide:

* [Getting Started with Account Setup](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-account-setup)

## Overview

This getting-started guide introduces the following concepts, procedures, and best practices for deploying Enterprise Agents and leveraging Cloud Agents:

* [Agents and Vantage Points](#agents-and-vantage-points)
* [Adding a New Enterprise Agent](#adding-a-new-enterprise-agent)
* [Preparing the Network](#preparing-the-network)
* [Adding Agent Labels](#adding-agent-labels)
* [Sharing Enterprise Agents Across Account Groups](#sharing-enterprise-agents-across-account-groups)
* [Setting Up Agent Notifications](#setting-up-agent-notifications)
* [Analyzing Agent Utilization](#analyzing-agent-utilization)

## Agents and Vantage Points

ThousandEyes' global vantage points are lightweight Linux-based software agents that allow users to run a variety of layered monitoring tests, in order to gain insight into network and application performance and user experience.

{% hint style="info" %}
ThousandEyes uses the terms global vantage points, vantage points, and agents throughout our documentation. These terms all refer to the same Linux-based software agents.
{% endhint %}

ThousandEyes provides three types of vantage points: Cloud Agents, Enterprise Agents, and [Endpoint Agents](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-endpoint-agents). Although each type of vantage point provides similar capabilities, they each serve different purposes, and exist in different environments.

This section provides a basic introduction into Cloud Agents and Enterprise Agents

### Cloud Agents

Cloud Agents are globally distributed vantage points, managed and maintained by the ThousandEyes Operations team, deployed in tier 2 and tier 3 Internet Service Providers, Internet exchange points, and cloud providers such as AWS, Google, Azure, and Alibaba. These vantage points are capable of running all network, DNS, web, transaction, and voice layer tests available within the ThousandEyes platform, and are available for use by all ThousandEyes customers on a unit consumption basis. You can use Cloud Agents to provide an "outside-in" or comparison view in places where campuses are located or where users and customers will be accessing sites. One of the advantages of using Cloud Agents is that you don't have to deploy any servers and can get service and network health visibility right away; then later you can add Enterprise Agents based on your requirements.

For more information about the location of ThousandEyes Cloud Agents, see the [Cloud Agent World Map](https://www.thousandeyes.com/product/cloud-agents).

### Enterprise Agents

Enterprise Agents are vantage points deployed locally (behind the firewalls of an organization) by customers to monitor their data centers, cloud VPCs/VNETs, branch offices, and other internal or Internet-based network assets. These vantage points are installed as either a package for a supported Linux distribution (see [Supported Enterprise Agent Operating Systems](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/supported-enterprise-agent-operating-systems)), or as a pre-packaged virtual appliance that can be deployed into a number of different hypervisor or hardware platforms.

Enterprise Agents should be placed where you want to run your test. For example, if you want to monitor your SaaS applications, Enterprise Agents should be placed at all locations where you have significant concentrations of users. In most cases, this means that each office will have a single Enterprise Agent. For some very large campuses, multiple agents can be deployed to monitor different parts of the campus.

{% hint style="info" %}
Unless your requirements dictate that you have floor and/or VLAN-based visibility, it is not usually necessary to install an Enterprise Agent on every floor of an office.
{% endhint %}

If ThousandEyes is used for monitoring application dependencies, such as external APIs, you should deploy an Enterprise Agent in the same datacenter as the application or use Cloud Agents. This will allow you to configure tests to the external API and quickly isolate issues.

{% hint style="info" %}
The following sections cover installing an agent for monitoring user applications from campus locations.
{% endhint %}

### Placement Inside the Location

The Enterprise Agent should be placed as close to the users as possible. Deploying the agent on an access switch, such as the Cisco Catalyst 9300, is a very efficient way to achieve that goal. If an access switch is not an option for deployment, you can use any deployment method mentioned in the [Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents) documentation, taking into consideration that the agent should be deployed as close to the users as possible.

### Choosing the Right Network

For most use cases, the best network to install the agent on is the same network as the user. This ensures that all dependencies that a user has (such as QoS policies, firewall policies, and routing) are also applicable to the ThousandEyes test traffic.

If multiple networks with distinct traffic policies exist (such as "users", "guests", and "voice"), multiple test sources will be needed. This can be achieved by either deploying multiple Enterprise Agents, or by configuring the multi-interface function.

## Adding a New Enterprise Agent

To add an Enterprise Agent:

1. Log into the ThousandEyes web application.
2. Navigate to **Network & App Synthetics > Agent Settings > Enterprise Agents > Agents**:

   ![Enterprise Agent Settings](/files/3n7FbKHBT7svuHlB6prz)
3. Click **Add New Enterprise Agent**. If this button is not visible, you'll need to review your user permissions. For more information, see [Role-Based Access Control](https://docs.thousandeyes.com/product-documentation/user-management/rbac/role-based-access-control-explained).

   After clicking the button, the installation menu panel will appear. This panel displays the installation options, system requirements, and the account group token, and links to the specific installation guides for each method.

   **Note:** The *account group token* is the unique key that links an Enterprise Agent to a ThousandEyes account group. Treat this token like a password.

   ![Add New Enterprise Agent dialog](/files/nry6YGs8K4YQxvFiywsC)
4. Follow the steps in the installation guide for your deployment method. When your new agent is successfully added, it will appear in the **Enterprise Agents > Agents** view.

   The **Status/Last Contact** column will show a green circle icon and the **Just Now** status for your newly created Enterprise Agent.

   ![Enterprise Agent list showing new agents](/files/9uyfTqebjGcTBANPymuS)

Your Enterprise Agent is now ready to use. We recommend you take the following steps with all new agents:

* Give them a descriptive agent name and hostname, to ensure they are easily identifiable.
* Add them to a single account group, then share them with other account groups for use in tests.

{% hint style="info" %}
ThousandEyes recommends that you assign all Enterprise Agents to a single account group and share them with other account groups for use in specific tests. This is the best practice because it ensures that one team is responsible for managing all agents.
{% endhint %}

{% hint style="info" %}
Enterprise Agents do not consume any licenses. It is the tests running on those agents that consume units. For more information, see [Our Consumption Models](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/our-consumption-models).

Some Cisco platforms include ThousandEyes units as part of their license, as outlined in the [Cisco Device Entitlements](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices#entitlements) section.
{% endhint %}

## Preparing the Network

Enterprise Agents need to connect to the ThousandEyes platform to function, and they need to be able to perform tests that send detailed output to the platform.

{% hint style="info" %}
All communication with the ThousandEyes platform from the Enterprise Agent is initiated by the agent, and so there is no requirement to configure inbound access from the ThousandEyes platform to the Enterprise Agent.
{% endhint %}

Network access for testing is dependent on the test type configured. For example, an HTTP test requires different ports and protocols than a DNS or voice test. For more information about test types, see [Getting Started with Tests](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-tests).

In order for the path visualization to properly function, you will need to allow ICMP error messages inbound to the Enterprise Agents. If a well-behaved stateful firewall is used, this should work automatically if outbound traffic is permitted, but in some cases, specific access will need to be configured.

The exact destination and protocols depend on your installation type, the tests performed, and the ThousandEyes region your account is provisioned in. For detailed firewall configuration requirements, see [Firewall Configuration for Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/firewall-configuration-for-enterprise-agents).

## Adding Agent Tags

When you configure a test, you can use an agenttag to assign multiple agents to that test. This makes agent selection easier, and ensures testing is configured consistently. In addition, these tags can be used to make dynamic dashboards that automatically adjust when the testing changes.

{% hint style="info" %}
The same tag can be applied to both Cloud and Enterprise Agents, and multiple tags can be applied to the same agent.
{% endhint %}

We recommend that you use labels to group similar agents together. For example, you could add labels for network segments (like "LAN", "VOICE", or "GUEST"), locations (countries, cities, regions etc), or internal classifications (like "Large Branch", "Datacenter" etc). You could also create labels specifically for Cloud Agents, such as a label for all agents used to monitor global websites and another for regional locations etc.

![Agent Labels tab grouping similar agents together](/files/S0lIyNSQFsdkINbKPAIM)

For more information on creating tags, see [Get started with tags](https://docs.thousandeyes.com/product-documentation/tags/tags-overview).

## Sharing Enterprise Agents Across Account Groups

As previously mentioned, ThousandEyes recommends that you assign all Enterprise Agents to a single account group, and then share access to the account groups that will be using the agents for testing, as shown in the following example:

![Enterprise Agent details screen for a selected Enterprise Agent](/files/xUUMPrBJVrlVqFOI5ClL)

By deploying agents this way, you ensure that there is a single place in the platform where all Enterprise Agents are visible, making management of these agents easier and more consistent, while maintaining control over who can initiate tests from individual agents.

## Setting Up Agent Notifications

Now that your Enterprise Agents are up and running, you will want to ensure they remain in a healthy state. One way to achieve this is to make sure you receive notifications when an error condition occurs.

Notification rules for Enterprise Agent conditions can be configured from the **Network and App Synthetics > Agent Settings > Enterprise Agents > Notifications** page of the ThousandEyes web application.

![Dialog for adding new notification rules](/files/j05aH7cUPgJk5CMWyWv8)

These notification rules/conditions can be set for:

* Agents being offline.
* Clock offset for an agent.
* Agent software being outdated.

## Analyzing Agent Utilization

Each test running on a ThousandEyes Enterprise Agent is assigned dedicated time in the test queues belonging to the agent. An Enterprise Agent can only run one task per queue at a time. This mechanism ensures that each test has dedicated resources, and that multiple tests won't interfere with each other.

Agent utilization is mostly dependent on server response times and queue utilization, so it will not help to add more resources to an overloaded agent. Adding more members to a cluster, or removing unnecessary tests, are the only ways to reduce agent load.

For more information about Enterprise Agent clustering and utilization, see [Enterprise Agent Utilization](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/enterprise-agent-utilization).


# Getting Started with Cloud and Enterprise Agent Tests

This article focuses on introducing you to ThousandEyes Network & App Synthetics tests. You will learn how to determine which type of test provides the best visibility, how to create a basic test, and how to interpret data, so that you can quickly resolve service disruptions.

## Prerequisites

This article assumes that you have previously read the following getting started documentation:

* [Getting Started with Account Setup](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-account-setup)
* [Getting Started with Cloud and Enterprise Agents](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-cloud-and-enterprise-agents)

## What is a Network and App Synthetics Test?

ThousandEyes helps organizations monitor their network and application performance using synthetic tests. These tests can be run on vantage points hosted all over the world ([Cloud Agents](https://www.thousandeyes.com/product/cloud-agents)) or deployed on customer hardware ([Enterprise Agents](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-enterprise-agents)), and allow organizations to make informed decisions about their network infrastructure and improve customer/user digital experience by helping troubleshoot issues with cloud-based or on-premises applications, services, and network connectivity.

## ThousandEyes Test Types

ThousandEyes provides a number of synthetic tests that can be categorized by their Open Systems Interconnection (OSI) layer. For more information about tests related to each layer, see the links below:

* [Network layer tests](https://docs.thousandeyes.com/product-documentation/tests#network-layer): These tests measure metrics like loss, latency, jitter, MTU, and path trace.
* [Routing layer tests](https://docs.thousandeyes.com/product-documentation/tests/working-with-test-settings#routing-layer-tests): These tests measure metrics like routing path changes, reachability, and BGP updates.
* [DNS layer tests](https://docs.thousandeyes.com/product-documentation/tests/working-with-test-settings#dns-layer-tests): These tests measure metrics like domain availability, resolution time, domain trace, and DNSSEC.
* [Web layer tests](https://docs.thousandeyes.com/product-documentation/tests/working-with-test-settings#web-layer-tests): These tests measure metrics like server availability, response time, throughput, redirects, response code, and page load performance.
* [Voice Layer tests](https://docs.thousandeyes.com/product-documentation/tests/working-with-test-settings#voice-layer-test): These tests measure SIP registration and RTP stream metrics.

## Determining the Targets

ThousandEyes recommends that you start by monitoring your most business-critical targets in the following categories.

### SaaS Applications

The most common use case for IT teams is monitoring business-critical cloud-hosted applications, such as Office365, Atlassian, Webex, or Slack.

These applications usually provide a public URL for each customer workspace, such as example.slack.com. While users share a single URL for web access, their requests can be served by different servers depending on the user's geolocation, resulting in different performance experiences based on connected networks and locations.

To emulate employee traffic, you need to configure tests that simulate how users connect to the network. We suggest using inside-out monitoring with Enterprise Agents deployed at each office network or VPN gateway.

ThousandEyes provides a number of agent deployment types, including virtual machines, Docker, NUCs, Raspberry Pis, and Cisco network devices. For more information on deployment types, see [Getting Started with Enterprise Agents](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-enterprise-agents).

### Internal Services

On-premises infrastructure that is hosted in a data center or server room (such as Active Directory, VoIP controllers, databases, or DNS resolvers) needs to be monitored to ensure a healthy network and application experience.

We recommend using HTTP, DNS, network, and VoIP tests that target critical on-premises services and applications from an Enterprise Agent deployed within your local area network (LAN).

{% hint style="info" %}
If you plan on using Enterprise Agents to monitor internal servers or network equipment that use internal DNS names, make sure to update the DNS configuration to use your internal resolver so that the hostnames can be resolved and reflected in the path view and traceroute output.
{% endhint %}

### WAN Sites

A modern WAN structure spreads user traffic among multiple locations connected by MPLS, EVPN, IPsec VPN, or SD-WAN. For users in an office to access a directory server hosted in a data center (DC), the network team needs to make sure their WAN links are constantly healthy. The application's backend could be hosted in different locations as well.

For example, the SRE team could manage a controller in DC1 and a database in DC2 to serve an application. In this example, any interruption of network services between DC1 and DC2 could cause service degradation for the application, and possibly result in a business-critical incident.

To ensure the highest availability of services, we suggest using agent-to-agent network tests with continuous monitoring between Enterprise Agents hosted in each of the WAN sites. Agent-to-agent tests can be configured to run bi-directional network tests every minute to detect network service disruptions or degradations. Additionally, agent-to-server tests can be configured to run with 1 second granularity for more sensitive services.

For more information about continuous monitoring, see [Continuous Monitoring](https://docs.thousandeyes.com/product-documentation/tests/network-tests/network-tests-explained#continuous-monitoring-for-one-minute-interval-tests).

### Cloud Sites

To address the need of a decoupled architecture, more and more businesses are shifting their services and workloads to cloud-hosting providers such as AWS, Azure, and Google Cloud.

For example, imagine that, rather than being hosted in a second datacenter, the SRE team migrates the database to AWS. In this instance, you can deploy an Enterprise Agent within the same AWS virtual private cloud (VPC) as your test target for an agent-to-agent test (in this case, the database service).

Alternatively, you can leverage the ThousandEyes Cloud Agents deployed in AWS, Azure, Google Cloud, and Alibaba Cloud.

For a full list of available Cloud Agents, see [Cloud Agents](https://www.thousandeyes.com/product/cloud-agents).

### Your Website

Many customers use ThousandEyes to monitor their public website's performance from all over the world. This outside-in visibility is not simple to measure, as it requires vantage points located everywhere.

ThousandEyes currently offers [Cloud Agents](https://www.thousandeyes.com/product/cloud-agents) in more than 240 locations around the world, and is continuously adding more. You can leverage these agents using HTTP, page load, and transaction tests to measure your website's performance. In addition to inside-out monitoring, this can detect outages from the user's perspective quickly, limiting impact.

## Deploying Tests

Once you know what you want to monitor, you can decide on the type of test/s that best suit your needs.

### Layered Tests

In a similar way to the OSI stack, layered tests build upon lower layer tests to create a more comprehensive view of correlated metrics. For example, an HTTP server test will incorporate an HTTP server connection, network layer agent-to-server test, and a BGP test, all monitoring the same target. In this way, users can measure metrics aligned to layers 3, 4, and 7 within the same round of a single test. The image below shows how tests are layered upon one another:

![Diagram of how layered tests build upon each other](/files/F41Iv32hcaHfoqfKOKBI)

Other examples of layered tests are shown below, with the additional tests they include:

* Transaction and page load tests:
  * HTTP server test
  * Agent-to-server test
  * BGP test
* HTTP, FTP, SIP, RTP, and DNS server tests:
  * Agent-to-server test
  * BGP test

{% hint style="info" %}
For any test targeting a server, ThousandEyes recommends always keeping the **Perform network measurements** and **Collect BPG data** advanced options enabled.

**Perform network measurements** will configure the agent to collect metrics from each layer of the network stack in the same round, which will be useful when doing root cause analysis for issues.

As ISP routing updates are a common cause of network issues, **Collect BGP data** will configure the agent to monitor BGP in order to help understand the dynamic nature of the public internet.

<img src="/files/Q9kpnDwPDNaDnVYFIeBX" alt="&#x22;Advanced Settings&#x22; tab" data-size="original">
{% endhint %}

The example image below shows the available views for an HTTP server test with both “Perform network measurements” and “Collect BGP data” enabled. These two settings ensure the layered test will provide details on both layer 4 (**Overview**, **Path Visualization**) and layer 3 (**BGP Route Visualization**), in addition to the HTTP server test data.

![Image shows response time metrics results from an HTTP server test](/files/XyfU4Rh3ioaIuO9Zsb9q)

#### Bi-Directional Tests

While most layered tests are designed to monitor one-way traffic, from the source agent to the target, some tests, like agent-to-agent tests, are designed to monitor source-to-target and target-to-source measurements during the same round, and then combine the two results together. These bi-directional tests can be especially helpful for isolating asymmetric routing issues. For more information, see [Agent-to-Agent Test Overview](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests/network-tests/agent-to-agent-test-overview).

### Standalone Tests

All ThousandEyes test types can also be performed as standalone tests, without additional layers. This can be useful alongside layered tests to support broader data collection. For example, DNS tests are not included in layered tests. For this reason, we suggest configuring a standalone DNS test alongside your layered test suite.

### Templates and Onboarding Wizard

The default landing page in the ThousandEyes application is the **Views** page. If you are a new user, the **Templates** app opens an onboarding wizard to walk you through the first steps. The wizard offers a smooth path to getting started with ThousandEyes. Choose a pre-configured template to start monitoring one of the common SaaS-based applications you use.

![Onboarding Wizard](/files/NLLiBjzHGVBOQct26cw5)

When the wizard finishes and you see **Setup completed successfully**, the UI is now populated with the results of your setup.

1. Click through the steps of the page tour.

   Explore the key elements of the **Views** screen:

   * Test selector
   * Timeline
   * Path visualization
2. On the **Dashboards** screen, click the selector and choose **Service Health Dashboard TEMPLATE**.
3. On the **Alert Rules** screen, check out the default.
4. On the **Test Settings** screen, you'll see the results of the tests that the wizard configured for you.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>The default page load test includes information from lower-layer tests: HTTP server, agent-to-server, and BGP tests. For more information about these test types, see:</p><ul><li><a href="https://docs.thousandeyes.com/product-documentation/tests#page-load-test">Web - Page load test</a></li><li><a href="https://docs.thousandeyes.com/product-documentation/tests#http-server-test">Web - HTTP server test</a></li><li><a href="https://docs.thousandeyes.com/product-documentation/tests#agent-to-server-test">Network - Agent-to-server test</a></li><li><a href="https://docs.thousandeyes.com/product-documentation/tests#bgp-test">Routing - BGP test</a></li></ul></div>

## Configuring Test Settings

Each test type has specific settings that need to be configured. You can find the detailed requirements for each test type by following the links in the [ThousandEyes Test Types](#thousandeyes-test-types) section of this article.

{% hint style="info" %}
ThousandEyes provides a number of templates for new users to automatically generate tests based on pre-configured settings. For more information about templates, see the [Onboarding Wizard](https://docs.thousandeyes.com/product-documentation/getting-started#onboarding-wizard) documentation.
{% endhint %}

To create a single test, navigate to **Network & App Synthetics > Test Settings**. Click **+ Add New Test** and select your desired test type from the **Quick Create** menu.

{% hint style="info" %}
Some fields are pre-filled based on the default configuration, but all basic settings for each request are required.
{% endhint %}

For this example, select **Agent to Server** from the **Network** category.

* **URL / Target / Domain / Prefix**: The target of the test.

  **Note:** For agent-to-agent and RTP tests, the **Target Agent** is selected from the agent list.
* **How often test runs**: The time between each test round. You can select from 1, 2, 5, 10, 15, 30 minutes, and 1 hour. BGP tests use 15 min by default.
* **Where test runs from**: The ThousandEyes agents to use for this test. Click the **Select Agents** button to open the agent selector modal, and then use the search functions and filters to find the agents you need. You can also toggle between the "Basic" and "Advanced" selectors depending on what view you prefer.

  **Note:** The modal defaults to the "Basic" view, but will remember your preference when closed.

  **Note:** For BGP tests, all public monitors will be included by default.

  ![Picking which agents are going to run the test - Basic](/files/vNww0s1NWoN8l89DcVVt)

  ![Picking which agents are going to run the test - Advanced](/files/ZxIzyuhgGlaZJ1x4RUYK)
* **Alert**s: Enable or disable alerts, select alert rules, and select suppression windows. For more information, see [Alerts](https://docs.thousandeyes.com/product-documentation/alerts).
* **Protocol / Ports / Probing Mode**: Only required for network tests.

  * For agent-to-server tests, select from `ICMP` or `TCP`.
  * For agent-to-agent tests, select from `TCP` or `UDP`.
  * For probing mode, select from `SACK` or `SYN`.

  For more information, see [Network Tests Explained](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests/network-tests/network-tests-explained).

{% hint style="warning" %}
In the metered subscription model, unit consumption is determined by test type, interval, timeout, and agent count. Before saving the test configuration, always check the **Projected Usage** field on the right panel to ensure your update will not exceed the organization's monthly unit allotment.

<img src="/files/JU8S4YANapJBa5X6A5mS" alt="Projected usage" data-size="original">

For more information, see [Calculating Units](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/calculating-units).
{% endhint %}

{% hint style="info" %}
Before creating any new test, ThousandEyes recommends running an instant test by clicking the **Run Once** button to verify the test is configured and working properly. Instant tests do not require many units, allowing you to understand the baseline functionality of a test, and determine which configuration options work best. This can be very useful when used in conjunction with creating [alert rules](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-alerts) for your tests.

Instant tests can also be run from the **Network & App Synthetics > Views** page. For more information about instant tests, see [Working with Instant Tests](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests/working-with-instant-tests).
{% endhint %}

## Interpreting Test Results

The **Network & App Synthetics > Views** page shows the scheduled test data for the past 30 days. Users can view test data from multiple charts and tables, and drill down into the data to identify issues and determine the root cause.

For a detailed explanation of the components of a view, see [Getting Started with Views](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/viewing-data/getting-started-with-views).

The main components in a test view are:

* The top panel contains the **Test Selector** and **Global Filters**.

  ![The test views top panel, showing the Test Selector and Global Filters](/files/NSXDmRhJCGAxnV8DxkB0)
* The primary panel contains the **Views List**, **Metric Selector**, and **Timeline**.

  ![The test views primary panel, showing the Views List, Metric Selector, and Timeline](/files/VNLJuD0gWrUQjtg5mp9L)
* The secondary panel contains the detailed metrics tabs, **Path Visualization**, and **BGP Route Visualization**.

  ![The test views secondary panel, showing the Map and Table tabs](/files/BsxK3yiE2xRrsyLnpogN)

Users can navigate through the views in a number of different ways. ThousandEyes recommends the following basic workflow:

1. Select the target test using the test selector.
2. Review the timeline of each test, and use the metric selector to view each available metric.
3. Once you find an event that stands out from the baseline, drill down into the detailed metrics tabs.
4. Try to identify the problematic agent in the table view, and click on it to filter the metrics by that agent.
5. Use the timeline to determine when the issues started for that agent.
6. Analyze the path visualization and BGP route visualization views for the specific round.

ThousandEyes agents collect multiple metrics for each test type. For more information on understanding your test results, see [What do your results mean?](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests/thousandeyes-metrics-what-do-your-results-mean).

To get started with the path visualization, see [Getting Started with the Path Visualization](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/viewing-data/getting-started-with-path-visualization).

## Troubleshooting Test Data

In the example outage below, we walk through the process of analyzing the issue and identifying the root problem. The example outage can be seen in this saved snapshot: [Example Outage](https://auvpkhdvyhzzoiabyjjtimpxtwdgcycn.share.thousandeyes.com).

The incident investigation starts with an alert triggered for the HTTP server’s availability:

![Results from an HTTP server test, showing a drop in availability](/files/66pZRvO4sE65MASjMKkr)

Switching to the **Table** view, you can confirm that the Paris and San Francisco agents were affected:

![Table view showing affected agents](/files/oOqO8d5pufKCgpzZs80L)

To review one agent, either use the global filter to select the Paris IPv6 agent, or click on the agent in the table. By navigating to the **Network Overview**, you can see the agent is showing 100% packet loss:

![Network Overview screen, filtered by the Paris agent](/files/ZyZKGFFZnIpNNZlerKSz)

If you switch to the **Path Visualization**, you can confirm that packets are being dropped in GTT's network, and there is no route to the IPv6 target in Microsoft's network.

![Path Visualization view showing dropped packets](/files/rk1MLyw0F9ToYsQGI4PU)

This implies that Microsoft may not be advertising this prefix to their routing peers. This can be easily verified using the BGP route visualization layer.

![BGP route visualization showing path changes](/files/qSfBU9VYXHZzsbKFBF2u) ![BGP route visualization showing the routes involved in BGP advertisement](/files/6xz6QAmeydOqZerwBFJZ)

As expected, you can confirm there was a path change involved with the target prefix, which caused reachability issues depicted by the BGP monitors. By selecting any monitor near Paris, you can see the path change details, which could impact the Paris agent network, and then make the necessary changes to correct the issue.

![Path changes picked up by the BGP monitor](/files/XsUnLSkxwzRGXg7vIJry)

## Sharing Test Data

The ThousandEyes platform test view (navigate to **Network & App Synthetics > Views**) provides a **Share** button for users to share test data with other ThousandEyes users, or external stakeholders that may or may not have access to the platform. You can collaborate with the same graphical view of test results, allowing you to troubleshoot with colleagues, partners, or providers, regardless of whether they subscribe to the ThousandEyes platform.

For sharing test data to anyone that does not have a ThousandEyes account, use the “Snapshots” sharelink feature, which is a unique read-only ThousandEyes test results web page.

![The Snapshot Sharing screen](/files/X8skrmASxloTfM6WZWuF)

For limiting access to test data, and sharing among ThousandEyes users, create a “Saved Event” which is stored under the **Sharing > Saved Events** menu list.

![Saving an event](/files/MoyxmdBGPv1UQ5v4XkMc)

In order to view or manage saved events, navigate to the **Sharing > Saved Events** menu. Click on the stacked icon next to the **Event Type** field to view an event, update the name of the saved event by clicking on the arrow icon, or delete it using the trashcan icon on the far right of the list.

Your user account will require the correct permissions to make these changes. For more information, see [Role-Based Access Control](https://docs.thousandeyes.com/product-documentation/user-management/rbac/role-based-access-control-explained).

For more information about sharing test data, see [Sharing Test Data](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests/sharing-test-data).

### Shared by ThousandEyes

For some of the most common SaaS-based applications, ThousandEyes has tests configured to monitor performance from Cloud Agents around the world. Instead of customers creating individual tests themselves, we share these tests with all customers. Tests shared by ThousandEyes don't cost units, and are also useful as example configurations for how to monitor applications.

To use these preconfigured tests, do the following:

1. Go to **Manage > Sharing > Shared by ThousandEyes**.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>The <strong>Shared by ThousandEyes</strong> page is available to organizations in the US1 <a href="https://docs.thousandeyes.com/product-documentation/user-management/user-activity/thousandeyes-multi-region-cloud-support">data residency region</a> only. It is not available in other data regions.</p></div>
2. Find the tests relevant to your organization, and click the **Enabled** checkbox.
3. Now you can
   * View the results of the test in **Network & App Synthetics > Views**.
   * Set up alerts for monitoring, as with any other test.

{% hint style="info" %}
Shared tests you have enabled will appear in your available tests list as read-only.
{% endhint %}

## Next Steps

For next steps and more advanced configurations, check out the following articles:

* [Getting Started with Dashboards](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-dashboards)
* [Getting Started with Views](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/viewing-data/getting-started-with-views)
* [Alerts](https://docs.thousandeyes.com/product-documentation/alerts)
* [Getting Started with Transactions](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-transactions)


# Getting Started with Endpoint Agents

As applications now run in the cloud and workers are more distributed, you can use ThousandEyes end-user monitoring with the [Endpoint Experience](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents) to gain visibility into your employees' experience of SaaS and internally hosted applications, as well as the underlying wireless LAN, WAN, internet connectivity, and system health.

## Endpoint Experience in the Broader ThousandEyes Ecosystem

Before learning how an Endpoint Experience works, let's first explore how the Endpoint Agent relates to the other ThousandEyes vantage points. First, compare the context-to-detail ratios of the different ThousandEyes products:

![Diagram explaining how ThousandEyes agents differ in how they show context versus detail](/files/Spa05jMixwxR2qNlLL9B)

* Internet Insights gives you macro-level visibility into outages that may affect you, using the collective intelligence of ThousandEyes. Answering questions like “Is my organization the only one having this issue”, “What is the blast radius of this outage”, or “Which set of providers has the most outages in a certain region”.
* Cloud and Enterprise Agents provide deep insights in your organization's digital experience. These always-on vantage points, the information they give, and the alerts they trigger are useful for identifying and isolating outages and performance degradations for the applications and locations tested.
* The Endpoint Experience provides the most detail, augmenting the path and application metrics with local browser, machine, and network data (including wireless).

{% hint style="warning" %}
The Endpoint Experience is a proactive tool. We do not recommend that you use the Endpoint Experience in a reactive manner by installing an agent ad-hoc when a user reports issues.

The Endpoint Experience monitors significant applications and network health, and silently connects to them in the background while users are actively working. This functionality enables support teams to retrospectively review the exact time an issue took place, which promotes a proactive response. Conversely, waiting for the error to resurface and then installing the agent is counterproductive.
{% endhint %}

## Choosing the Right Targets for Agent Installation

The first task in your Endpoint Agent deployment is to plan where to install agents. The most successful customers install the Endpoint Agent on a broad set of users, preferably every machine in the organization. This broad distribution allows you to troubleshoot the most issues and provides important trending information on application performance.

{% hint style="info" %}
**Best Practice: Bulk Installation**

A successful ThousandEyes deployment shouldn’t depend on the manual installation of agents. Involve your organization's desktop team early in the planning process so your organization can do an automated installation.

Before you deploy the automated installation, make sure that the browser plugin is included in the installation package. For guidance on how to create a bulk install, see [Install Endpoint Experiences for Windows via Group Policy](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/installing/install-the-endpoint-agent).
{% endhint %}

## Leveraging Endpoint Agent Labels

Once your Endpoint Agents are installed, use *labels* to assign tests to agents, and to make dashboards based on these labels.

{% hint style="info" %}
Unlike a Cloud or Enterprise Agent, an Endpoint Agent is dynamic by nature. The owner of a laptop could be in the office with wired Ethernet, or working from a coffee shop on wireless. You will likely want to run different tests depending on the particular device context: for example, you should only test internal applications for endpoints that are connected to the VPN or internal network.
{% endhint %}

For detailed information on creating dynamic tags, see [Manage dynamic tags for Endpoint Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/configuring/dynamic-tags).

### Start with Common Labels

Any particular label configuration will be organization-specific, but there are some good places to start. Consider creating specific labels around the following categories:

* Connection-based: wired, wireless, and VPN connections.
* Location-based: relevant parts of the world, the country you are located in, building or floor, etc.
* Network-based: office networks, or important ISPs where remote workers are working from, to gain insights into performance differences between different groups of remote workers.
* Agent-specific: only for specific agents based on organizational groups, rather than being dynamically assigned based on device conditions.

#### Example

Let's say you want to create connection-based labels.

To create the labels for **wired** and **wireless**, the process is straightforward: When you configure your labels, set the **Connection** field to “Ethernet” or “Wireless”.

To create the label for VPN-connected Endpoint Agent, there are multiple ways of selecting VPN users. You can base the selection on VPN vendor, gateway address, client network, or client IP. The image below shows selection based on the VPN client network, adding the **VPN** label to every agent that is part of any VPN network.

Navigate to **Endpoint Experience > Agent Settings > Agent Labels > Add New Label**:

![The Edit Label screen for Endpoint Agent labels](/files/SdJ6I8C1cFHfnnUuWFMb)

## Configuring Endpoint Experience Tests

After installing the agent, you need to configure the right set of tests. The ThousandEyes Endpoint Experience provides you with the following different types of tests:

* [Real user tests](#browser-session-tests) dynamically capture website, network, and agent details using the ThousandEyes Endpoint Experience browser plug-in. Based on the session and agent statistics, an *experience score* is computed to help you better understand the user's interactions.
* [Synthetic Tests](http://docs.thousandeyes.com/product-documentation/end-user-monitoring/test-settings/synthetic-tests): A synthetic test template combines scheduled and dynamic tests to monitor a specific application. All the major applications have a defined synthetic test template, and you can also create a custom template for applications that do not have a predefined template.
  * [Scheduled tests](#scheduled-tests) are HTTP server or network tests that are run from Endpoint Experience at regularly scheduled intervals. Hence, you get a continuous baseline from the end user's vantage point.
  * [Dynamic tests](#automated-session-tests) automatically identify and test remote targets for collaboration applications, based on observed network connections to dynamic remote servers.

### Real User Tests

Real user tests are recorded automatically when the user visits a website in the monitored domain set.

A *monitored domain set* consists of domains you want to gather end-user performance metrics about. The best practice is using business-relevant domains for tools and sites your end users access.

To configure real user tests:

1. Navigate to the **Endpoint Experience > Test Settings > Real User Tests** tab.
2. Click the **Add New Monitored Domain Set** button.
3. Configure the basic settings for the session.
4. Assign the agents that run the real user test for this Monitored Domain Set. There are three options available:

* All Agents: The test is assigned to all available agents. This is selected by default.
* Specific Agents: The test is assigned to user-defined agents. You can select the agents from the drop-down or the search function.
* Agent Labels: The agent is assigned based on pre-configured dynamic tags. See [Manage dynamic tags for Endpoint Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/configuring/dynamic-tags) for more information.

5. Click **Add New Monitored Domain Set** at the bottom to save the domain, or click **Cancel** to discard the changes.

![The Add New Monitored Domain Set screen](/files/EK0qR7mGB6jKiMRc0CRx)

In the example image above, a new monitored domain set (called "BusinessDomains”) is created, with three domains added: ThousandEyes.com, Cisco.com, and CiscoLive.com.

{% hint style="info" %}
A monitored domain set includes all of its subdomains. For example, adding `microsoft.com` to a monitored domain set automatically includes `office.microsoft.com` in real user tests.
{% endhint %}

For more information on real user tests, see [Real User Tests View](https://docs.thousandeyes.com/product-documentation/end-user-monitoring/viewing-data/endpoint-agent-browser-sessions-view).

### Scheduled Tests

Scheduled tests monitor the availability and performance of web applications or network targets. For example, use them to test corporate VPN gateways or critical business applications.

To configure a scheduled test, go to **Endpoint Experience > Test Settings**. You can configure a web-based or network test, and set a test interval ranging from every minute to once every hour.

A powerful feature of scheduled tests is the ability to test based on the Endpoint Agent [dynamic tag](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/configuring/dynamic-tags) (as shown in the image below).

![](/files/7zI4kbXRmymOYFr4oTOC)

The example test in the image above executes on agents that have the **VPN** label. This ensures that the test is not run for users who do not have access to the corporate network. At the bottom of the **Add New Test** dialog, you can find the agents that currently match this label.

When getting started with scheduled tests for Endpoint Experience, consider the sites and applications your users rely on, and create tests that provide the best visibility.

### Dynamic Tests

Dynamic Tests enable the Endpoint Experience to monitor and identify network connections between an end-user’s application and the destination node (host server). This removes the ambiguity surrounding which applications require testing. Dynamic tests monitor applications, such as collaboration and communication tools like Webex. As you begin your Endpoint Experience, we recommend enabling dynamic tests for the collaboration apps your organization uses.

The Endpoint Experience watches for remote connections from specific applications on the user’s machine, and automatically runs tests toward those remote targets. For example, a dynamic test for Webex will detect when a user joins a Webex meeting and will execute tests from the Endpoint Experience to the various remote Webex servers used in that specific meeting, such as the multimedia platform and collaboration bridge.

### Test Priority

An Endpoint Agent can run up to 10 concurrent scheduled tests and one dynamic test.

To ensure that the more relevant tests are executed when the total number of tests assigned to an agent exceeds 10, you can pre-define a *priority* for the tests.

![How to prioritize tests in the Add New Test dialog](/files/E7dS3yKDN59fyIx7qgps)

In general, prioritization of tests is for dynamic tests; however, you can also prioritize scheduled tests.

{% hint style="info" %}
Be sure to enable the **Prioritize** switch for all dynamic tests. For more information on how tests are assigned to agents, see [Assign Tests to an Endpoint Experience](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/assign_tests_to_agents).
{% endhint %}

## Using the Endpoint Experience to Solve User Problems

This section describes how to use the Endpoint Experience to resolve user issues.

{% hint style="info" %}
As a pre-requisite, ensure that the devices in your organization have the Endpoint Agent installed, a monitored domain set is active, scheduled tests are running, and dynamic tests are watching your critical applications.
{% endhint %}

There are three primary ways to start investigating endpoint issues:

* The test-centric approach, via the [**Endpoint Experience > Overview** screen](#overview)
* The user-centric approach, via the [**Endpoint Experience > Agent Views** screen](#agent-views)
* The detailed approach, via the [**Endpoint Experience > Views** screen](#detailed-view)

### Overview

The first place to investigate an issue is on the **Endpoint Experience > Overview** screen.

![The Endpoint Experience > Overview screen](/files/HeThtabLdHnhvuZQr42D)

The **Overview** provides a high-level summary of both real user tests and scheduled tests. The default view shows you the worst results, allowing you to identify the issue quickly and start working on it.

All the URLs and test names in this view are clickable links that redirect you to the corresponding scheduled tests or real user tests. This enables you to follow up on generic issues in your environment more easily.

### Agent Views

The helpdesk or IT support staff in your organization are the primary consumers of the **Endpoint Experience > Agent Views** screen.

In this view, you can search for a specific agent and see all the information related to that agent's scheduled tests, dynamic tests, local networks, and real user test data.

![The Agent Views screen](/files/bEKkYaL6gMxJLPIo28yH)

Using this view, you can easily click on the metric and jump to a detailed view that is pre-filtered for the selected agent.

For more information on **Agent Views**, see [Endpoint Experience Views](https://docs.thousandeyes.com/product-documentation/end-user-monitoring/viewing-data/single-agent-view).

### Detailed View

The **Endpoint Experience > Views** screen provides you with all the test details and results for all Endpoint Experience. Use the filter drop-down at the top of the screen to see the data associated with agents, destinations, networks, or VPNs. For more information on **Views** and how the different filters work, refer to the [Viewing Data](https://docs.thousandeyes.com/product-documentation/end-user-monitoring/viewing-data) documentation.

### Endpoint Events

{% hint style="info" %}
Any information provided in this document regarding future functionalities is for informational purposes only and is subject to change including ceasing any further development of such functionality. Many of these future functionalities remain in varying stages of development and will be offered on a when-and-if available basis, and Cisco makes no commitment as to the final delivery of any of such future functionalities. Cisco will have no liability for Cisco's failure to deliver any or all future functionalities and any such failure would not in any way imply the right to return any previously purchased Cisco products.
{% endhint %}

Events for Endpoint Agent provide automated, real-time visibility into critical system and network changes that impact the end-user experience. These events capture significant occurrences—such as Wi-Fi signal degradation, high CPU utilization, or issues in the local gateway—and correlate them directly with network performance metrics. By using these events for troubleshooting, you can quickly identify the root cause of intermittent connectivity issues and reduce the time spent on manual log analysis. This streamlined approach allows you to determine whether a performance drop was triggered by a local device change or an external network event, accelerating the path to resolution.

For more information on **Events**, refer to the [Event Detection](https://docs.thousandeyes.com/product-documentation/event-detection) documentation.

### Example of Troubleshooting

In this example, we walk through a real-life scenario of how to use the ThousandEyes Endpoint Experience for troubleshooting.

The user here experiences a sudden “slowness” when connecting to web applications, and as usual “they didn’t change anything”. This is a common complaint reported by all help desk personnel.

{% hint style="info" %}
Use [this snapshot](https://tspng.share.thousandeyes.com/view/endpoint-agent/?roundId=1623197100\&metric=experience-score\&scenarioId=visitedSites\&filters=N4IgZglgNgLgpgJwM4gFygLYEMDGALCAOzgEkATNAbRAHYAmOgFgGYBOAIzAFodWaAOLoxpl2XLPxrMucVlgCMABj5gAbHRyMQAXQC%2BuoA\&testId=56116\&tabId=overview) to go through this example yourself.
{% endhint %}

Start your troubleshooting by selecting the **Visited Pages** view. In the image below, we see this screen, filtered by the agent belonging to the user with the complaints (`lindsayc`)

![The Visited Pages view](/files/z8GVlDKFnenGpcQy8LOS)

At 01:00, the moment shown, the experience looks good, matching what the user describes. The following supports that statement:

* The average experience score is 95%, close to perfect.
* The overall page speed is “Fast”.
* There are no errors on the page.

The image below shows the same user one hour later. Here, we see the experience score is now 67%, significantly lower than the 95% earlier.

![The Visited Pages view, showing a lower experience score](/files/Rpd2Py1Bq4hOw5oHkW1l)

This information helps you to acknowledge the problem the user is experiencing. This is an important first step when your help desk is in conversation with an user who is experiencing application, network, or system-related issues.

The next step is identifying the root cause of the problem. Under **Experience score by agent**, click the agent name to zoom in on the details for the real user test in this specific time window.

![Details about the experience score for this agent](/files/mHQ5HXrYa1yQKsCztzC1)

The image above shows that the client is connected to the wireless network “AndroidAP” with a very low quality. The SSID name suggests that this is a cellular connection, and not office wifi, explaining the sudden drop in user experience.

You can find details about all the different view options for the Endpoint Experience in [Viewing Endpoint Data](https://docs.thousandeyes.com/product-documentation/end-user-monitoring/viewing-data).

## Building Dynamic Dashboards Based on Labels

In [Leveraging Endpoint Agent Labels](#leveraging-endpoint-agent-labels), we used labels to determine which agent should run a specific test. Another, equally powerful use of labels is in dashboards. Use labels for grouping and selecting agents, resulting in dynamic dashboards.

![](/files/lKhXtp5AYlfjIXvkEasZ)

In the image above, you can see the options to configure a new widget in a dashboard. As an example, we will compare wireless and wired application experience.

1. Log in to the ThousandEyes platform and go to **Dashboards**.
2. To create a new dashboard, click the three dots or ellipsis menu and select **Create New Dashboard**.
3. Once you've created your dashboard, click **+ Add Widget** and select the **Color Grid**.
4. Fill in the fields as follows:
   * **Widget Name**: **Wireless** or **Wired**, per site
   * **Data Source**: Endpoint Real User Tests
   * **Category**: Visited Pages
   * **Metric**: Experience Score
   * **Group Cards by**: Endpoint Experience Label
   * **Drill Down**: Select the labels **Wired** and **Wireless**. (You must [create the labels](#leveraging-endpoint-agent-labels) before creating this widget.)
5. Click **Save**.

The picture below shows the comparison between wired and wireless performance. In this case, wireless has a better performance across the entire organization.

![Dashboard widgets comparing wireless and wired performance](/files/Tph8XLXn4M8bvkLPK7dE)

For more information about ThousandEyes dashboards, see [Dashboards](https://docs.thousandeyes.com/product-documentation/dashboards).

## Next Steps

After completing this getting-started guide, the following links will help you on the rest of your journey in getting the most out of the ThousandEyes Endpoint Experience.

* [Monitoring Webex Meetings with Endpoint Agents](https://docs.thousandeyes.com/solution-guides/monitoring-applications-and-services/monitoring-webex-meeting-with-epa)
* [Optimizing Microsoft Teams Performance and Availability](https://www.thousandeyes.com/blog/optimizing-microsoft-teams-performance-availability)
* [Best Practices to Create a “Remote Workforce” Dashboard](https://www.thousandeyes.com/blog/best-practices-create-remote-workforce-dashboard)
* [Endpoint Experience Browser Session Recording](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/quick-guide-on-endpoint-agent#working-with-endpoint-agents)
* [Answering Common Questions About Endpoint Experience](https://www.thousandeyes.com/blog/answering-common-questions-endpoint-agent)
* [Endpoint Experience FAQ](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/endpoint-agent-faq)
* [Endpoint Agent Documentation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents)


# Getting Started with Transactions

## Introduction

ThousandEyes transaction tests are Web layer tests similar to HTTP server tests and page load tests, except that transaction tests can interact with their targets in order to mimic multi-step user journeys or API sequences. Transaction tests provide greater insight into user experience, and enable you to ensure that those user journeys complete successfully.

Compare these three web layer test types below:

| [HTTP Server Test](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests/http-server-tests)                                                                                                                                                                     | [Page Load Test](https://docs.thousandeyes.com/product-documentation/browser-synthetics/page-load-tests)                                                                                                                                                                                                                                                                                                                                                                    | [Transaction Test](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests)                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The ThousandEyes Cloud or Enterprise Agent sends a single request and expects a single valid response. Measures response time and validates the HTTP status code to compute server availability. HTTP server tests are used to monitor web servers to ensure they are available and performant. | ThousandEyes agent runs Chromium in order to request and render a single web page. Chromium sends an initial request for the page, then renders the response, and iteratively requests all of the components within the page, including images, JavaScript files, CSS, and AJAX requests. Page load tests monitor the web server that serves the page and all of the page's dependencies. A page load test can be thought of as multiple HTTP server tests combined in one. | <p><em>Browser Synthetics</em>: Agent runs Chromium which is automatically driven by a Selenium script. The script can navigate through multiple pages and interact with them. A browser synthetics transaction test can be thought of as multiple page load tests combined in one.</p><p><em>API Monitoring</em>: Agent runs a script in <code>Node.js</code> to sequentially or iteratively make arbitrary API requests towards the target using the <code>node-fetch</code> library.</p> |

### When to Use a Transaction Test

Transaction tests measure web user experience using either synthetic browser interactions, or sequences of API requests. Transaction tests should be used for testing *multi-step workflows*. This type of test can uncover problems that aren't always apparent from loading a single page, as with a page load test, or sending a single request, as with an HTTP server test. For example, if your app or web site relies on returning customer data from somewhere else after the user logs in, you'll need a transaction test to evaluate this part of the user experience past the login screen.

Some examples of transaction tests include:

* **Productivity SaaS:** Log in, browse to a shared documents folder, and download a file.
* **Shopping/e-commerce:** Load the main page, search for a specific product by name, add it to a shopping cart, and complete the purchase using a dummy credit card.
* **Web conferencing:** Log in, schedule a meeting, and join the meeting in the browser with a virtual camera and microphone

### Terminology

* **BrowserBot** is a component of the ThousandEyes [Cloud Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/cloud-agents) and [Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents) that manages page load and transaction tests. This is accomplished by running an instance of the Chromium web browser which can be driven automatically via Selenium from Node.js. Complete details are available in the [What is BrowserBot?](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/what-is-browserbot) article.
* **Selenium** is an open source software library for browser automation. Transaction tests leverage the Selenium API in Node.js for automating the Chromium web browser.
* **node-fetch** is an open source software library for making HTTP requests. Transaction tests leverage node-fetch within Node.js for API monitoring, allowing you to script machine-to-machine workflows such as back-end API call sequences.
* **Node.js** is a JavaScript runtime environment included in BrowserBot which is used to execute scripts for transaction tests.
* **JavaScript** is the programming language in which transaction scripts are written. You do not need to be a JavaScript expert to work with transaction tests, but some JavaScript knowledge will allow you to create more advanced transaction scripts.

## Getting Started with the Recorder IDE

### Requirements

The Recorder IDE has two modes, based on your permission settings. Both modes require the *API Access* permission and either the *Login via ThousandEyes login page* or *Login via Single Sign-On* permission.

* **Standalone Mode**: Allows the user to use the IDE for standalone test creation. No additional permissions required.
* **Test Creation Mode**: Allows the user to create tests and export (upload) the tests to the ThousandEyes platform at app.thousandeyes.com. This mode additionally requires the *Edit tests*, *Create web transaction tests*, *View agents in account group*, and *View labels* permissions.

Refer to the [ThousandEyes Recorder Permissions](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/getting-started/thousandeyes-recorder-permissions) article for full details.

### Downloading and Installing the Recorder IDE

* Windows - Windows 7 or later - [Download - Windows exe](https://downloads.thousandeyes.com/tedit/recorder/ThousandEyesRecorderIDE.exe)
* macOS - MacOS 10.10 (Yosemite) or later - [Download - Mac dmg](https://downloads.thousandeyes.com/tedit/recorder/ThousandEyesRecorderIDE.dmg)
* Linux - Ubuntu 12.04 or later - [Download Linux AppImage](https://downloads.thousandeyes.com/tedit/recorder/ThousandEyesRecorderIDE.AppImage)

Follow the normal installation process for your computer's operating system. For example, the macOS version of the ThousandEyes Recorder downloads as a disk image (.dmg) file. Double-click the downloaded file and a macOS installation dialog opens. In that dialog, drag the application icon into your Applications folder.

### First Time Setup

After completing the installation, launch the ThousandEyes Recorder IDE. The first time you use the Recorder IDE, you will be prompted to login to your ThousandEyes account. To log in:

1. Enter your email address and click **Log In**.
2. ThousandEyes automatically detects your authentication method:

   * If your organization uses local login, enter your password and click **Log In**.
   * If your organization supports Single Sign-On (SSO) and your user permissions allow it, you are either redirected to your identity provider or taken to a login screen where you can choose to log in with SSO or continue with local login.

   For more login information, see [Logging In](https://docs.thousandeyes.com/product-documentation/user-management/authentication/logging-in).

<img src="/files/WDXZGeiNjuTP4uiAOQ47" alt="Email Login Screen" width="400">

After completing the login flow, the Recorder IDE may flash briefly while it verifies your user has the necessary permissions. After this, it should look like the screenshot below.

![The ThousandEyes Recorder IDE](/files/8julg7xBoi8bGBL1McyG)

If the Recorder IDE shows the message "You Do Not Have Permissions to Create Tests", as seen below, double check that your ThousandEyes user is assigned a role with the requisite permissions.

![Recorder IDE screen, displaying a restricted permissions warning](/files/gNviG13D0nKfwzpG9eGT)

You may also change your current account group by clicking on your e-mail address in the top right corner.

![Dropdown menu for changing the current account group](/files/bNAHbuyYtexNAYCAGYvl)

For complete details on using the ThousandEyes Recorder IDE, refer to the [ThousandEyes Recorder](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/getting-started/thousandeyes-recorder) article.

## Browser Synthetics Development Workflow

![Flowchart of Browser Synthetics development](/files/d98DZyusiVJkEIKbZfS0)

## Recording a Browser Transaction

Click the **Record** button (![Window to set up Browser Recording settings](/files/X0P4fMLXsjk6Wcip2QHY)) and the Recorder IDE will prompt you to type a URL to record. You may also configure the browser window size and orientation. After typing a URL, click **Start Recording** and the Recorder IDE will launch a Chromium browser window which will automatically navigate to that URL.

![A screen recording example using the Google website](/files/zFsE0Oe6wRv3wdyIIQnL)

The browser will record your interactions, such as clicking on buttons or typing text in form fields, and use them to automatically generate a transaction script. When you have finished your recording, go back to the Recorder IDE window and click the **Stop** button (![Visual representation of Stop button](/files/lggKDnUv0cY59A1lcLkG)).

As an example, click the **Record** button and type <https://google.com> in the **Enter Base URL** field, then click the **Start Recording** button. When the Chromium window has opened and loaded <https://google.com>, click on the search field, then type "ThousandEyes product documentation", and then press the "Enter" key. On the search results page, click the link to the ThousandEyes product documentation site. Then go back to the Recorder IDE window and click the **Stop** button.

![Example of generating a transaction script with the recorder](/files/Ghrze6MpTIRyMGDIzRdd)

After clicking the **Stop** button, the Recorder IDE will close the Chromium window and generate a transaction script for automating the workflow you just recorded. In this example, you should expect to see a script generated like the one below:

```javascript
import { By, Key } from 'selenium-webdriver';
import { driver, test } from 'thousandeyes';

runScript();

async function runScript() {
  
   await configureDriver();

   const settings = test.getSettings();

   // Load page
   await driver.get(settings.url);
  
   // Click on 'Search'
   await click(By.name(`q`));

   await typeText('thousandeyes product documentation', By.name(`q`));

   await pressEnter(By.name(`q`));

   // Click on 'ThousandEyes Documentation - Thousa...'
    await click(By.css(`[href="https://docs.thousandeyes.com/"] > .LC20lb`));
  
}
```

You have now successfully recorded your first transaction test. The next step in the browser synthetics development workflow is to play the test to verify it works as expected. If you would like a better understanding of the generated code for this transaction script, continue on to the next section below. Otherwise, jump ahead to the [Playback](#playback) section.

#### Breaking down the script line by line

The first two lines of the script are import declarations. The transaction script runs in Node.js, a JavaScript runtime environment, and allows us to import code from outside of the script. In this case, the Recorder IDE automatically imported code from two packages named "selenium-webdriver" and "thousandeyes".

```javascript
import { By, Key } from 'selenium-webdriver';
```

The first declaration, shown above, imports a class named `By` and an enumeration named `Key` from Selenium. The [`By`](https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/index_exports_By.html) class is used for specifying the method for locating an element within a webpage. To interact with an element, like clicking on it or typing into it, Selenium must first be able to locate the element. Elements will be generally located in one of the following ways:

* `className`: Locates elements that have a specific class name.
* `css`: Locates elements using a CSS selector
* `id`: Locates elements by the ID attribute
* `linkText`: Locates link elements whose visible text matches the given string
* `name`: Locates elements whose name attribute has the given value
* `xpath`: Locates elements matching a XPath selector

The [`Key`](https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/index_exports_Key.html) enumeration provides representations of pressable keys that aren't text, such as the Alt, Shift, Tab, and Enter keys. The Recorder IDE imported this enumeration because we pressed the Enter key while recording.

```javascript
import { driver, test } from 'thousandeyes';
```

The second declaration imports two modules provided by ThousandEyes. The first module, `driver` , is an instance of Selenium's [`WebDriver`](https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/index_exports_WebDriver.html) class that has been instantiated to work with the Chromium browser on the agent. Refer to the [Controlling the Browser section of the Transaction Scripting Reference](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/transaction-scripting-reference#controlling-the-browser) for the full list of supported methods. The second module, `test`, provides an interface to the transaction test configuration, such as getting the target test URL or test interval. Refer to the [Getting Test Configuration Settings section of the Transaction Scripting Reference](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/transaction-scripting-reference#getting-test-configuration-settings) for full documentation and example usage.

```javascript
runScript();
```

The line above calls the `runScript` function, which contains the interactions that were recorded. The `runScript`function is defined in the following lines.

```javascript
async function runScript() {
```

This line begins the definition for `runScript` function.

```javascript
   await configureDriver();
```

This line calls the `configureDriver` function which is provided by the Recorder IDE. The `configureDriver` function configures the driver instance's implicit timeout. The implicit timeout specifies the maximum amount of time to wait when attempting to locate elements on the page. Without calling `configureDriver`, the default value is 0 which is not very forgiving on modern websites and will often throw errors that elements could not be found because the page had not fully loaded. When `configureDriver` is used, the value is set to 7 seconds.

```javascript
  const settings = test.getSettings();
```

This line calls the `getSettings` method from the `test` module and stores the result in a variable named `settings`.

```javascript
  await driver.get(settings.url);
```

This line calls the `get` method of the `driver` instance to navigate to a specific URL. It references the settings variable from the previous line to use the target URL from the test configuration.

```javascript
  await click(By.name(`q`));
```

This line is generated from clicking on the search field on the Google search page. It calls a function named `click`, which is provided by the Recorder IDE, with an element selector using `By.name`, which was imported earlier from Selenium. The value of the name selector, "q", corresponds to the HTML name attribute of the search field on Google’s page.

```javascript
  await typeText('thousandeyes product documentation', By.name(`q`));
```

The `typeText` function is provided by the Recorder IDE as a helper function for typing text into a given field. It accepts two parameters: first, the text to type, and second, a selector to locate the element in which to type that text.

```javascript
  await pressEnter(By.name(`q`));
```

The `pressEnter` function is provided by the Recorder IDE as a helper function for pressing the enter key. It accepts one parameter, a selector to locate the element in which to press the Enter key.

```javascript
  await click(By.css(`[href="https://docs.thousandeyes.com/"] > .LC20lb`));
```

The last line in the runScript function is generated from clicking on the ThousandEyes Product Documentation link on the search results page. Here, the Recorder IDE used a different selector, `By.css` to locate the link.

```javascript
}
```

The closing curly brace concludes the definition of the `runScript` function.

The helper functions mentioned above that are generated and included by the Recorder IDE, such as `configureDriver`, `click`, `typeText`, and `pressEnter`, are defined below the the definition of the runScript function.

## Playback

Once you have recorded a transaction, you can play the script to test that it works as expected. Click the **Play** button (![Visual representation of Play button](/files/mu5JON83ioadv7W8GWEo)) and the Recorder IDE will launch Chromium to execute the Transaction script.

![Playing back a generated script to test it](/files/TRE6w4J9lHaOX8sl0TTp)

If everything worked correctly, the Chromium window will close and no errors will be reported. If your test playback worked successfully, then you should [optimize](#optimize) the script by adding markers, screenshots, and configuring credentials, then [export](#export-to-thousandeyes-platform) the script as a scheduled transaction test in the ThousandEyes platform.

If any errors were encountered while executing the script, they will be reported in the Recorder IDE’s console located in the bottom pane of the window, as seen below. When an error occurs, the Recorder IDE will also capture a screenshot from the browser and highlight the lines of code leading to the error. If your test playback encountered errors, then you should proceed to [troubleshooting](#troubleshooting) the script so that it correctly and completely emulates the user journey without errors.

![An example of errors displayed in the Recorder IDE's console](/files/UoQn8KxwmB4DlJC6sKWH)

## Optimize

Once your transaction script successfully plays back without any errors, you should optimize the script with the features described below. After adding your optimizations, be sure to play the transaction again to verify it still works as expected.

### Markers

You can use markers to define and measure discrete steps within a user journey or business transaction. For example, an e-commerce checkout transaction may include steps for "Item Search", "Add to Cart", and "Submit Order", and each step may include multiple actions like clicking and typing. Markers are used to delineate such steps and measure the time taken for each. By identifying where a script section starts and stops, markers can be compared to over test rounds and to the overall transaction time. If the performance of the whole transaction degrades, markers allow you to quickly see which step(s) in the transaction took longer to complete than they normally would. When an error occurs inside of a marker, the marker will show as "Incomplete" in the test view which can identify the specific phase of the transaction that had an error. Marker times are displayed on the timeline and waterfall in transaction test views and can also be used in alert rules and dashboards.

![Diagram displaying Search and Add to Cart transaction steps and the length of time for each step](/files/USivKm83NqHzTmupAlXM)

There are two ways to use markers:

* the `set` method creates a marker with the supplied name that spans from transaction start time to the time this method is called
* the `start` and `stop` methods start and stop a marker with the supplied name at the time they are called

To use markers in your script, you must include the `markers` module in the `thousandeyes` import line at the top of the script.

```javascript
import { driver, markers, test } from 'thousandeyes';
```

Clicking the **Add marker** button (![Visual representation of Add marker button](/files/rnnh2Iu7QHCpIzDqb1gp)) will:

* Add `markers` to the `import { ... } from 'thousandeyes'` import declaration, if the module is not already imported
* Add two lines of code for `markers.start` and `markers.stop` at the cursor position in the script editor

The `markers` module is documented in the [Transaction Scripting Reference](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/transaction-scripting-reference#markers). The code below shows how to add markers to the example script from the [Recording a Browser Transaction section](#Recording-a-Browser-Transaction) above.

```javascript
import { By, Key } from 'selenium-webdriver';
import { driver, markers, test } from 'thousandeyes';

runScript();

async function runScript() {
  
  await configureDriver();
  const settings = test.getSettings();
  await driver.get(settings.url);  

  // Using markers.set, the ‘Initial Page Load’ marker spans from transaction start time 
  // to the time the initial page finishes loading
  markers.set('Initial Page Load');
  
  // Using markers.start, the ‘Search’ marker begins measuring time after the initial page loaded
  markers.start('Search');
  await click(By.name(`q`));
  await typeText('thousandeyes product documentation', By.name(`q`));
  await pressEnter(By.name(`q`));
  // Using markers.stop, the `Search` marker ends when the user submits the search form
  markers.stop('Search');  


  markers.start('Product Docs');
  await click(By.css(`[href="https://docs.thousandeyes.com/"] > .LC20lb`));
  markers.stop('Product Docs');
}
```

### Screenshots

Screenshots are useful to track progress and ensure the page visually matches what you were intending to see. You can capture a screenshot of the browser’s viewport by adding the following line of code inside your script. Clicking the **Take screenshot** button (![Visual representation of Take screenshot button](/files/n5LfZenEmMc4077vTPvj)) will add this line of code at the cursor position in the script editor. No additional import declarations are required because the takeScreenshot method belongs to the driver class that has already been imported after the recording.

```javascript
  await driver.takeScreenshot();
```

There is no limit to the number of screenshots that can be captured during a transaction, but only the last three screenshots will be included with the test results in the platform as described in [Screenshots in Transaction Test Views](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/getting-started/screenshots-in-transaction-test-views). It can still be useful to capture more than three screenshots because if the script encounters an error before completing, you can inspect the state of the webpage leading up to the error. One screenshot will be automatically captured at the time the error occurs.

Capturing screenshots requires a small-but-non-zero amount of time on the order of one half second. Whenever possible screenshots should not be captured gratuitously and should be captured after stopping one marker and before starting the next.

You can disable screenshots by unchecking the **Screenshots > Enabled** checkbox in the test's **Advanced Settings** tab in the ThousandEyes platform. Unchecking this box will prevent screenshots from being captured when `driver.takeScreenshot()` is called or when an error occurs.

### Credentials

The Recorder IDE’s Chromium browser will record the keys you press while interacting with a page. Recall from the example Google search transaction that typing in the search form resulted in this line in the transaction script:

```javascript
  await typeText('thousandeyes product documentation', By.name(`q`));
```

In some cases, such as typing in password forms, you may not want to store the values you typed as cleartext in the transaction script. ThousandEyes provides a credential repository which is used to store and retrieve sensitive information like passwords, authentication tokens, or two-factor authentication secrets.

The Recorder IDE will automatically use the credentials repository if you record typing in an input field with a type attribute equal to "password". As an example, start a new recording on the URL <https://app.thousandeyes.com> and when the Chromium window opens and loads the ThousandEyes login page, click on the **Password** input field and type some text, and then click the **Log In** button. Switch back to the Recorder IDE window, click the **Stop** button.

Notice how the call to the `typeText` function differs from the earlier example:

```javascript
  await typeText(credentials.get('pass_1674485288249'), By.id(`password`));
```

The Recorder IDE detected we were typing in a "password" field and automatically stored the value as a local credential rather than using a plaintext string. Instead of seeing the characters you typed, the first parameter of the `typeText` function is now a call to `credentials.get` with a credential name of "pass\_1674485288249". The credential name is generated using the current unix timestamp to avoid naming collisions with other credentials. While you can use the credential with its default name, the recommended best practice is to update the credential name to something meaningful or identifiable.

Credentials can be managed in the Recorder IDE’s credentials dialog by clicking the **Show credentials** button (![Visual representation of Show creditials button](/files/j1feiYLXviT3p9Od97Qg)). This dialog contains two sections: the credential repository from the ThousandEyes platform and local credentials (those that have not yet been synced to the ThousandEyes platform). To rename a credential, hover over the credential name in the list, then click the pencil icon. Then, you can edit both the name and the value of the credential. Click the **Update Credential** button to save your changes.

| Credentials List                                    | Credential Details                                                            |
| --------------------------------------------------- | ----------------------------------------------------------------------------- |
| ![List of credentials](/files/mspTsJDWlo0T74inPPUK) | ![Editing th details of a particular credential](/files/OeubS7aZEZp9vpezSm3J) |

After you rename a credential, be sure to modify the name in any calls to credentials.get that used the old name. For example, if you rename the "pass\_1674485288249" credential to "myPassword", then you must update the `typeText` line from above like so:

```javascript
  await typeText(credentials.get('myPassword'), By.id(`password`));
```

You can also sync the credential to the ThousandEyes platform by hovering over the credential name in the list and clicking the **Save to ThousandEyes** icon. If you plan to export this transaction to the platform, you should sync your credential now.

## Troubleshooting

You may find that some recorded transactions will raise an unexpected error during playback in the Recorder IDE or while running on Cloud and Enterprise Agents in the ThousandEyes platform. While many recorded flows will result in fully functional scripts that work on the first playback, at times it will be necessary to manually alter the recorded output. This section will help you to troubleshoot your transaction scripts to identify the cause of errors and how to fix them.

To most effectively troubleshoot transaction scripts, you should have some familiarity with the browser's web development tools. See the [Working With Web Development Tools](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/getting-started/working-with-web-development-tools) article for more information and resources.

### Useful Functions for Troubleshooting

#### `console.log`

You can use `console.log` statements to help debug, such as printing the current line number, e.g. `console.log("Line 7")`, or the value of a variable, e.g, `console.log(settings.url)`.

#### `driver.sleep`

You can use `driver.sleep` to slow down script execution when debugging or if you want to sit at one step for a long time (for instance, to inspect elements in the page using the web development tools). The `driver.sleep` function takes a single parameter, the amount of time to sleep in milliseconds. Example usage:

```javascript
    // Sleep for 5 seconds
    await driver.sleep(5 * 1000);
```

Clicking the **Add sleep** button ![Visual representation of Add sleep button](/files/I58UbKHqNVma3sc57NuC) will insert code to call `driver.sleep` at the cursor position in the script editor.

### Common Errors

#### NoSuchElementError

The most common error is `NoSuchElementError` which indicates that Selenium was unable to locate an element within the page with the given selector. This usually occurs for one of the reasons explained below.

**Element did not exist (yet)**

Today's web applications commonly use client-side rendering to build their pages. Compared to server-side rendering, which generates the full HTML document and sends it to the client in the initial request, with client-side rendering the server only sends an initial scaffold in the first request and then uses JavaScript to dynamically fetch data and render it in the page. Selenium will begin its attempt to locate an element after the initial page load, but does not necessarily wait for all the JavaScript to finish executing.

If the transaction is failing because it cannot locate an element, you can try increasing the `implicit` value in the `configureDriver` function. For example, the code below sets the implicit wait to 15 seconds, a little more than double the Recorder IDE's default value. Note that the value is in milliseconds, which is why `* 1000` is used.

```javascript
async function configureDriver() {
    await driver.manage().setTimeouts({
        implicit: 15 * 1000, // If an element is not found, reattempt for this many milliseconds
    });
}
```

**Element did exist, but selector did not match**

Some pages contain elements that do not have consistent attributes which may cause the Recorder IDE to choose a selector that matches while recording but does not match during playback. There are two easy ways to identify if this is the cause of your `NoSuchElementError`:

1. Use the `console.log` and `driver.sleep` functions immediately before the line of code which raises the `NoSuchElementError` and play the transaction again. After the browser opens, switch back to the Recorder IDE and when you see your log message in the Recorder IDE's console, hit the **Pause** button. Return to the browser and use the web development tools to inspect the element, comparing its attributes with the selector used in the script. It may be helpful to repeat this more than once.
2. Re-record your transaction and compare the selector(s) between the first and second recordings. Make sure to copy or save the original recording before starting a new one because the new recording will overwrite the original script in the script editor.

**Element was in a different tab or window**

Some browser actions may cause a new browser tab (or window) to open. While the Recorder IDE will continue to record your actions in other tabs, it does not record when you switch between them. This can lead to the script looking for an element in one page when it exists in another page in a different tab.

To change the active tab, you can use the `driver.switchTo` function. Two examples are available in the [transaction scripting examples repository](https://github.com/thousandeyes/transaction-scripting-examples):

1. [`switchToNextTab.js`](https://github.com/thousandeyes/transaction-scripting-examples/blob/master/examples/switchToNextTab.js): Shows how to switch to the next tab, including wrapping around to the first tab from the last tab
2. [`switchToTabWithUrl.js`](https://github.com/thousandeyes/transaction-scripting-examples/blob/master/examples/switchToTabWithUrl.js): Shows how to switch to a specific tab given its URL

#### ElementClickInterceptedError

The `ElementClickInterceptedError` will occur when Selenium attempts to click on an element but it is covered by one or more other elements. This can happen when the web page uses the CSS `z-index` property to overlay elements on top of other elements. This normally occurs when a popup dialog is shown or when sticky navigation bars or footers scroll with the page.

To avoid this error, be sure to wait for and dismiss any automatic modal popups while recording. If the target element is covered by a sticky navbar or footer, try using the [`scrollElementIntoView`](https://github.com/thousandeyes/transaction-scripting-examples/blob/master/examples/scrollElementIntoView.js) function from the from the transaction scripting examples repository.

#### ElementNotInteractableError and WebDriverError: element not interactable

These errors will occur when Selenium attempts to interact (e.g, click on or type into) with an element that is not visible. In contrast to the `NoSuchElementError`, the element does exist and was successfully located, but Selenium cannot interact with it because it is not rendered in the page.

This commonly occurs when interacting with an element that is only visible while hovering the mouse pointer over a particular part of the page. The Recorder IDE does not record mouse hover events, so you will need to add the code to move the mouse pointer. There are two ways you may be able to resolve this issue:

1. Re-record the transaction and try clicking the element, not just hovering over it. Many pages will handle clicks and hovers the the same way, though some may handle them differently.
2. Use the `moveMouseInto` function from [`moveMouseIntoElement.js`](https://github.com/thousandeyes/transaction-scripting-examples/blob/master/examples/moveMouseIntoElement.js) in the transaction scripting examples repository to move the mouse pointer to a specific element and trigger hover events.

#### TimeoutError: Transaction timed out

This error occurs when the configured test timeout is reached before the script has completed. To prevent this error, you can increase the test timeout or reduce the runtime of the script. For example, you can make the script run faster by minimizing or removing use of `driver.sleep`. If your transaction is lengthy or complex with lots of steps, consider breaking it down into two or more separate transactions.

The maximum configurable timeout is dependent on the test interval:

* 60 seconds for 2 minute tests
* 150 seconds for 5 minute tests
* 180 seconds for 10+ minute tests

To configure the timeout in the Recorder IDE, click the **Show settings** button (![Visual representation of Show settings button](/files/spY9mufiqGuisXRTyIvo)) and adjust the **Timeout** slider in the **Advanced Settings** tab. To configure the timeout in the ThousandEyes platform, go to the **Test Settings** page, find and expand the test in the list, and adjust the **Timeout** slider in **Transaction Timing** section of the **Advanced Settings** tab.

## Export to ThousandEyes Platform

After you've recorded, optimized, and played back your transaction, you are ready to export it from the Recorder IDE to the ThousandEyes platform. Click the **Export to ThousandEyes** button to open the **Test Settings** dialog where you can select the test interval and agents, associate alert rules, and configure other advanced settings.

| Basic Settings                                                         | Browser Options                                                         | Advanced Settings                                                         |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| ![The Test Settings > Basic Settings tab](/files/dd5JXKaMCigp5kqwzc0N) | ![The Test Settings > Browser Options tab](/files/gVkYL3oYC1qZdo2lByYp) | ![The Test Settings > Advanced Settings tab](/files/XknZm7cc2Xd32tBiQvAM) |

{% hint style="info" %}
As mentioned in the [Requirements](#requirements) section above, exporting to the ThousandEyes platform requires the necessary permissions to use the Recorder IDE in Test Creation Mode. If you are using the Recorder IDE in Standalone Mode, you can save your transaction script locally to share it with your ThousandEyes administrator. Click the **More actions** button ![](/files/ICi22mjRWxOIlVrk1V9u), then click the **Save Script** menu item.
{% endhint %}

When you are finished configuring the settings, click the **Export** button and the Recorder IDE will create a new test in the ThousandEyes platform. When it's finished, you should see a confirmation dialog indicating the test was successfully saved. Click the **View test** link in this dialog to open the test settings in platform and validate the test.

![Dialog confirming test creation was successfully saved](/files/Kfilt68fUQeaLXx4wZte)

If you are using the Recorder IDE in Test Creation Mode and your script uses any credentials which have not been synced to the ThousandEyes platform, you will receive a confirmation dialog to create the test. You can either click the **Cancel** button and sync the credentials before creating the test, or you can click **Create Test** and then sync the credentials afterwards.

![The Test Settings - Credentials dialog](/files/oNB71QFuRKnVyUBDFXKD)

## Validate

It is important to validate that the transaction runs successfully on the agents in the platform even though you have already played back the transaction locally in the Recorder IDE. The Recorder IDE is very closely related to the BrowserBot that runs inside the ThousandEyes Cloud or Enterprise Agent, but the they are not identical. This means that in some transactions, a script which successfully played back in the Recorder IDE may fail when run from agents in the platform.

After you export your test, click the **View test** link in the success dialog to open the test settings in platform. At the bottom of the test settings panel, click the **Run Once** button to run an instant test in a new browser tab. Wait for the test results and then verify that all of the agents successfully completed the transaction. If any errors occur, click the **Run Again** link above the timeline in the view to determine if the error is consistent or intermittent. Then, refer back to the [troubleshooting](#troubleshooting) section to determine the cause of the error.

#### My script works in the recorder, but fails in the platform. Why?

**User Agent**: The default curl user agent we use for HTTP tests is rejected by many larger sites. You should supply a chrome user agent or similar so that all layers use the same UA. You can configure the user agent in the **HTTP Request** section of the **Advanced Settings** tab in the test's settings.

**Agent Location**: Scripts that work fine locally may fail on agents in other regions, as they may be routed differently, land on different sites etc. Make sure you rule out any location specific issues.

**Agent Network Conditions**: The time that network requests take can have an impact on whether your script works or not. For example, if you have a driver.sleep command that waits for 5 seconds, that may work for you but not be sufficient for an agent in some far off rural area. It's best to not use hard coded sleep values, but instead use waits with sufficient timeouts.

**Authentication**: If you test an application that uses Integrated Windows Authentication (IWA), it may behave differently while recording in Windows than it does while running on the Linux-based cloud and enterprise agents. IWA, sometimes called "silent authentication", uses your Windows credentials to automatically authenticate to a web server without an interactive login form, resulting in a different transaction workflow from a Windows device than a cloud or enterprise agent. IWA is commonly used for internal applications or intranet sites, but may also be used with SaaS applications when they are configured with federated single sign-on.

**Network Security**: When the transaction runs on the agent, it is almost always from a different network than where it was originally recorded. This can cause different firewall or proxy rules to apply and block the traffic coming from the agent. If the transaction test completes during playback in the Recorder IDE but fails in the ThousandEyes platform, you should check the network layer metrics and path visualization to ensure the agent is able to reach the target. For Enterprise Agents, you may need to [configure a proxy](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/proxy/configuring-an-enterprise-agent-to-use-a-proxy-server) or verify that the [necessary fire rules](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/firewall-configuration-for-enterprise-agents) are in place.

## Using the Transaction Test View

When you export a Transaction test, you can see the test data under **Network & App Synthetics > Views**. The Transaction view leverages the ThousandEyes standard layout, [documented here](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/viewing-data#thousandeyes-standard-layout). For general information on the ThousandEyes standard view layout, see [Getting Started with Views](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-views). This section highlights specifics shown in the Transaction view.

### Transaction View, Timeline

![The Transactions view, showing the timeline](/files/mN2pyI9qNXeCghLzTN7Y)

The top of the Transaction view shows a timeline similar to other views, with a time period slider below. Three metrics can be displayed on the timeline:

* **Transaction Time (default):** The amount of time spent running the transaction test. When Transaction Time is selected, you may also select up to three markers to view on the timeline
* **Errors:** The number of timeout errors, page errors, assert errors, and other errors that occurred in the test round
* **Completion:** Whether or not the transaction completed without errors

When a single agent is selected, you can mouse over the error indicator in the swimlane under the timeline to view the specific error details.

### Transaction View, Map

![The Transactions view's map tab, showing global results from agents running tests](/files/kca4gsy4ObPhHV0RxhcQ)

The **Map** tab as shown below displays a global map showing all of the agents that are running the test, with a **Metrics** panel to summarize data and any error messages reported by the agents. Clicking on an agent in the map will select that agent in the **Agent** selector above the timeline. The color of the agents shown on the map indicates the speed relative to the test duration, as specified by the **Timeout** parameter in the **Advanced Settings** tab for the test configuration in **Network & App Synthetics > Test Settings**.

The **Metrics** panel shows the transaction time (average, when all agents are selected) and when a single agent is selected also shows the individual marker times.

![The Metrics panel, showing global agents' transaction times](/files/3QVKYT49WbvqFf7JBkEr)

### Transaction View, Table

![The Transaction view's Table tab, showing test results from selected test rounds](/files/gv9lE5W4I8AyqwbrBpMX)

The **Table** tab shows test details from the selected test round for each agent. If any errors occur during the transaction, the agent will be shown in the table with a red dot next to its name. You can mouse over this icon to view specific error details. Clicking on an agent in the table will select that agent in the **Agent** selector above the timeline.

For more details on the transaction view table, see the [Transaction Test Table Tab View](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/getting-started/transaction-test-table-tab-view) article.

### Transaction View, Waterfall

![The Transaction view's Waterfall tab, showing details about pages, markers, and screenshots](/files/qTvnyAugrPFSZCZUkgyG)

The **Waterfall** tab in the transaction view is similar to the **Waterfall** tab in the page load view, with three additional features at the top of the chart:

* **Pages**: Because transaction tests can navigate through more than one page, the waterfall chart in the transactions view indicates each page that is visited and the duration of time spent on that page. You can mouse over a page in the **Page** row to view the page's duration. You can click on a page to filter the waterfall chart to only include components from that page.
* **Markers**: Markers are exclusive to transaction tests. The waterfall chart for transactions includes a visualization of the marker timings over the duration of the transaction. You can mouse over a marker in the **Markers** row to view the marker's exact timing. You can click a marker to filter the waterfall chart to only include components during that marker.
* **Screenshots**: The last three screenshots captured during the transaction will be stored with the test data and displayed on the **Waterfall** tab. You can mouse over the picture icon in the **Screenshots** row to view the captured screenshot. The horizontal position of the icon in the row indicates the relative point in time during the transaction that the screenshot was captured.

For complete details on the **Waterfall** tab, see the [Navigating Waterfall Charts for Page Load and Transaction Tests](https://docs.thousandeyes.com/product-documentation/browser-synthetics/navigating-waterfall-charts-for-page-load-and-transaction-tests) article.

## Resources

### ThousandEyes Product Documentation

* [What is BrowserBot?](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/what-is-browserbot)
* [ThousandEyes Recorder](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/getting-started/thousandeyes-recorder)
* [Role-Based Access Control, Explained](https://docs.thousandeyes.com/product-documentation/user-management/rbac/role-based-access-control-explained)
* [Transaction Scripting Reference](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/transaction-scripting-reference)
* [Working With Secure Credentials](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/getting-started/working-with-secure-credentials)
* [Working With Web Development Tools](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/getting-started/working-with-web-development-tools)
* [ThousandEyes Standard Layout](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/viewing-data#thousandeyes-standard-layout)
* [Getting Started with Views](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-views)
* [Transaction Test Table Tab View](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/getting-started/transaction-test-table-tab-view)
* [Navigating Waterfall Charts for Page Load and Transaction Tests](https://docs.thousandeyes.com/product-documentation/browser-synthetics/navigating-waterfall-charts-for-page-load-and-transaction-tests)

### External Resources

* [Troubleshooting synthetics scripts](https://github.com/thousandeyes/transaction-scripting-examples/wiki/Troubleshooting-synthetics-scripts)
* [Selenium javascript API documentation](https://www.selenium.dev/selenium/docs/api/javascript/index.html)


# Getting Started with Dashboards

Dashboards are powerful tools to visualize your ThousandEyes tests, quickly isolate issues, and see the health of your infrastructure and applications. Before starting, it’s recommended to consider who will use the dashboard, identify the key metrics, and which tests will provide the best visibility.

Unless you are creating a dashboard using Internet Insights or Application Outages as a data source you will need to have tests created and actively running. Also, you can create agent tags and test tags for grouping the data. See [Get started with tags](https://docs.thousandeyes.com/product-documentation/tags/tags-overview) for more information.

## Key Topics

* [Dashboard Widget Types and Sharing Widgets](#dashboard-widget-types-and-sharing-widgets)
* [Create a Dashboard (5-10 minute step by step instructions)](#create-a-dashboard)
* [Dashboard Display Settings](#dashboard-display-settings)
* [Duplicating Dashboards](#duplicating-dashboards)
* [Dashboard Permissions and Labels](#dashboard-permissions-and-labels)
* [Save or Download a Dashboard Snapshot](#save-or-download-a-dashboard-snapshot)
* [Schedule a Dashboard Snapshot](#schedule-a-dashboard-snapshot)

## Dashboard Widget Types and Sharing Widgets

You can learn about all the different widget types in the [Dashboard Widgets Types document](https://docs.thousandeyes.com/product-documentation/dashboards/dashboard-widgets).

One of the critical features of the ThousandEyes widget is that you can make changes, instantly see what the data will look like, and then decide to save the settings. If the widget is not showing the data that will provide you or your team with the best view you can revert it or continue to test out different filters and settings by updating the data source, metrics, measure, agents, etc. When widgets are aligned and set up with the proper metrics it can drastically improve your ability to troubleshoot and resolve issues in your environment. You can easily position tests showing a side by side inside-out and outside-in view or create a visualization to show you the critical metrics for different circuits and services in one dashboard.

Dashboard widgets can also be shared out to third party systems that can view iframes. For more information see [Embedding Dashboard Widgets in External Sites](https://docs.thousandeyes.com/product-documentation/dashboards/embedding-dashboard-widgets-in-external-web-sites).

## Create a Dashboard

Before you create a dashboard, you should consider who is the end-user and what is the purpose of the dashboard. This information will help you determine which tests from your environment will be used to configure the widgets and which metrics will provide the best visibility into your critical services.

### Pre-requisites for Creating a Sample Dashboard

We’ll use three different test types for this dashboard but if you don’t have these tests configured in your environment feel free to experiment with others: DNS, Network - Agent to Server and a Web - HTTP Server Test (Note: this could also be a Web - Page Load or Web - Transaction test as these all have Web - HTTP Server metrics). For more information on tests see [Getting Started with Tests](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-tests).

### Seven Steps to Create as Sample Dashboard

Here's an example of a dashboard once it's completed. It should take between 5-10 minutes to complete based on the below step-by-step instructions:

![My Dashboard Sample](/files/ei5nJFjWjogBPluLa4jR)

### Step 1: Log in and Create a New Dashboard

Log in to the ThousandEyes platform and access the Dashboard Menu. you will be directed to a built-in dashboard called ThousandEyes Built-in unless your account group already has created a default dashboard and set it up for your default login account group. To create a new dashboard, click the **“...” Options** or **ellipsis** menu and select **Create New Dashboard**.

![Create New Dashboard](/files/IS7532Mses1dbNZAuzNR)

This opens the **Create New Dashboard** window and settings. For this example, name the dashboard **My Dashboard** and click **Create Dashboard**:

![Create New Dashboard Pane](/files/UXint2vcLhsB64hhrXfs)

* **Name:** For this example, use **My Dashboard**. Ensure you provide a unique name to your dashboard. Using an existing name prompts the error message: **Name Not Unique** below the dashboard name field.
* Click **Create Dashboard**

### Step 2: Add a Number Widget

You can start to add widgets and make it into a functional view of your tests and metrics. In this case, start with the [number widget](https://docs.thousandeyes.com/product-documentation/dashboards/dashboard-widgets#number-widget) to quickly show the overall health of the packet loss, latency, and jitter from your underlying DNS and Web - HTTP Server and Network - Agent to Server test. In the upper right corner of your dashboard click the **+Add Widget** button and the widget pane appears:

![My Dashboard Add Widget](/files/wE9GFVTsutqjpKLqZomX)

Click or drag the **Number Widget** on to the dashboard causing the number widget configuration pane to appear:

![Add Number - Number Widget](/files/uD9PMgCQyVdmNFP0f9W3)

To configure the Number Widget, you need to update so it will start to show useful metric data. Here’s how the first card will look:

{% hint style="info" %}
**Note:** most of the selections are card specific and the selections will be reflected in the card view which can easily be duplicated and then modified for the other cards.
{% endhint %}

![Editing Number Widget - Packet Loss](/files/nvOHFM8iFPgGH2VNSah1)

* **Widget Name:** Network Health
* **Data Source:** Cloud & Enterprise Agents
* **Category:** Network - Agent to Server
* **Metric:** Packet Loss
* **Measure:** Mean (other selections can be Maximum, Median, Minimum, nth Percentile or Standard 6. Deviation)
* **Card Name:** Packet Loss
* **Drill Down:** Select Tests and individually select your DNS, Network - Agent to Server and Web - HTTP Server Test.

{% hint style="info" %}
Drill downs can be used as filters, and you can select multiple filters for Agents, Agent Tags, Tests, Test Tags, and Servers.
{% endhint %}

Click **+Duplicate Card** and update the next card as shown below:

![Editing Number Widget - Latency](/files/YPN6ANWT0Tn9jDOO7oLD)

* **Metric:** Latency
* **Card Name:** Latency

Click **+Duplicate Card** and update the next card as shown below:

![Editing Number Widget - Jitter](/files/O6t8NlpVtVVnmgkCYdbl)

* **Metric:** Jitter
* **Card Name:** Jitter
* Click **Save** as you’ve completed your first widget! Your dashboard should look like the below screenshot:

![My Dashboard Number Widget](/files/UgAMkvG7hNDCF5extLHa)

### Step 3: Add a Color Grid Widget

In the upper right corner of your dashboard click **+ Add Widget** and click the **Color Grid widget**:

![Add Widget - Color Grid](/files/nF8HSbukZDoIS7Oj9e2v)

In this example, you will configure the color widget to show latency for the tests grouped by the agents from where the tests are being performed. This will make it so you can see which location is having an issue with latency. You can learn more about the color grid widget in our [documentation](https://docs.thousandeyes.com/product-documentation/dashboards/dashboard-widgets#color-grid-widget). Update the color widget as shown in the screenshot below:

![Edit Color Grid Widget - Latency](/files/6NOt8WAgNZdCYAwv6mzX)

* **Widget Name:** Latency (by Agent)
* **Data Source:** Cloud & Enterprise Agents
* **Category:** Network - Agent to Server
* **Metric:** Latency
* **Measure:** Mean
* **Cards:** Tests
* **Group Cards By:** Agents
* **Sort Cards By:** Value (Descending)
* **Columns:** 2
* **Drilldown:** Select **Tests** and individually select your DNS, Network - Agent to Server and Web - HTTP Server Test.
* Click **Save** and you should see a widget in your dashboard that looks something like the below screenshot:

![My Dashboard - Color Grid Widget](/files/B7GgHsKz41sjreS5Q3sI)

### Step 4: Add a Stacked Bar Widget

In the upper right corner of your dashboard click **+ Add Widget** and click the **Stacked Bar widget** from the Breakdown section as shown below:

![Add Widget - Breakdown - Stacked Bar](/files/TwVKMwDvBbyawVFe4aO3)

You can configure the stacked bar chart to show the metrics that make up your HTTP Total Time when it’s measured from your test agents. This will allow you to easily visualize DNS Time, Connect Time, SSL Time, Wait Time and Receive Time. You can find out more about the stacked bar widget in our [documentation](https://docs.thousandeyes.com/product-documentation/dashboards/dashboard-widgets#stacked-bar-widget). Configure the stacked bar chart widget as show in the screenshot below:

![Edit Stacked Bar Widget - HTTP Total Time](/files/5rQ9cMj92vKjPHQAlR93)

* **Widget Name:** HTTP Total Time (by Agent)
* **Data Source:** Cloud & Enterprise Agents
* **Category:** Web - HTTP Server
* **Metric:** Total Time
* **Measure:** Mean
* **Y-Axis:** Agents and be sure change the bars to be horizontal for better visibility
* **Sort by:** Value
* **Drill Down:** Select your Web - HTTP Server (this will work for Web - Page Load and Web - Transaction tests as well)
* Click **Save** and you should see a widget that looks like the below screenshot that clearly breaks down the important metrics that results in your http total time from each agent’s perspective:

![My Dashboard - Stacked Bar Widget](/files/ynfeeyZPRILcLpLUkxWJ)

### Step 5: Add a Time Series Line Widget

In the upper right corner of your dashboard click **+ Add Widget** and click the **Line widget** from the Time Series section as shown below:

![Add Widget - Time Series - Line](/files/RG0Ynr4rCe0kJbdXZunh)

The time series line widget provides great visibility so you can see changes in any number of metrics over time. In this example you will be able to quickly see if packet loss has changed over the day with any of your tests. Configure the time series line widget as show in the screenshot below:

![Edit Time Series Line Widget - Packet Loss](/files/aQ3dl15ggOKIYRXiV4Xl)

* **Widget Name:** Packet Loss (by Test)
* **Data Source:** Cloud & Enterprise Agents
* **Category:** Network - Agent to Server
* **Metric:** Packet Loss
* **Measure:** Mean
* **Group By:** Tests
* **Drilldown:** Select Tests and individually select your DNS, Network - Agent to Server and Web - HTTP Server Test.
* Click **Save** and you should see a widget like the below screenshot:

![My Dashboard - Time Series Line Widget](/files/lmbBE5UWgnSE3Vzoj7yP)

### Step 6: Add a Live Status Tests Widget

In the upper right corner of your dashboard click **+ Add Widget** and click the **Tests widget** from the Live Status section as shown below:

![Add Widget - Live Status - Tests](/files/4wx7vUm3nQ4g7MfwYgDj)

The live status test widget provides a powerful visual of your tests and their primary metrics over the last 12 hours in a spark view so you can quickly troubleshoot if an issue spans multiple tests or if there was a change in the metric. It also provides a link to the test, the test settings, and a visual indicator if there is an active alert including a link to the alert. You can find out more about the test widget in our [documentation](https://docs.thousandeyes.com/product-documentation/dashboards/dashboard-widgets#tests-widget). Configure the test widget as shown in the below screenshot:

![Edit Live Status Tests Widget - Test IDs](/files/n0ypl7wAUUKwCQK2Z6DS)

* **Widget Name:** Google Tests (in this case all the tests are to Google but be sure to use a logical name based off the tests you chose for this example or just use Tests)
* **Data Filter:** Click **any** and select the **Tests IDs** for your DNS, Network - Agent to Server and Web - HTTP Server Test
* Click **Save** and you should see a widget like the screenshot below:

![My Dashboard - Tests Widget](/files/gYN7xw07mmaNFspfogKL)

### Step 7: Add a Live Status Alert List Widget

This is the last widget for this sample dashboard. In the upper right corner of your dashboard click **+ Add Widget** and click the **Alert List widget** from the Live Status section as shown below:

![Add Widget - Live Status - Alert List](/files/dI65aJI6DjhzZZ04n9Wc)

The alert list widget will display the alerts as well as their duration and will indicate if they are active. You can find out more about the alert list widget in our [documentation](https://docs.thousandeyes.com/product-documentation/dashboards/dashboard-widgets#alert-list-widget). Configure the alert list widget as shown in the below screenshot:

![Edit Live Status Alert List - Tests](/files/TsVlW6TPEFqg0xk05rxH)

* **Drilldown:** Select **Tests** and individually select your DNS, Network - Agent to Server and Web - HTTP Server Test.
* Click **Save** and now you’re all done!

![My Dashboard - Alert List Widget](/files/YMbpHWDbIJoFInvLA7H8)

Now that you’ve created your first dashboard if you want to dive in deeper be sure to check our documentation on [dashboard customization](https://docs.thousandeyes.com/product-documentation/dashboards/customizing-your-dashboard), the different [types of widgets](https://docs.thousandeyes.com/product-documentation/dashboards/dashboard-widgets) and our [best practices guides](https://docs.thousandeyes.com/solution-guides/best-practices).

## Dashboard Display Settings

Now that you have a dashboard configured, you may want to view it with data for a particular time interval to use it for troubleshooting an outage or visualizing your network or service performance during a specific time range. To accomplish this, click the **Dashboard Time selector** and select the relative time ranges using the quick select options or customize the time range using the fixed time interval as shown in the below screenshot. **Note:** The timeframe of the Live widgets (Tests, Alert list, Map) cannot be updated. After you select your custom time, you must **toggle** the global time override button otherwise the time selection will not be applied.

![Dashboard Display Settings Time Options](/files/SImUZzkKHzFVyCrsj0Qj)

* **Relative Time Interval:** These are quick time selections based on the most commonly used time intervals
* **Fixed Time Intervals:** This can be used if you want to select a custom date and time to be reflected in the dashboard widgets.
* **Global Time Override Button:** This must be toggled on for your selection to be applied to the dashboard widgets.

The following is an example using a relative time interval of last 7 days:

![Dashboard Display Settings - Last 7 Days](/files/zXi0FBMBCJiPlh23l4m4)

* **Relative Time Interval:** Last 7 days
* **Global Time Override Button:** Toggle on so you see the blue indicator
* **Widget:** Updated to show the last 7 days

If you’d like to learn more about dashboard display settings please check our [documentation](https://docs.thousandeyes.com/product-documentation/dashboards/customizing-your-dashboard#configuring-dashboard-display-settings).

## Duplicating Dashboards

There are many different reasons you might want to duplicate a dashboard. For example, another team member has created one, but it doesn’t exactly match your needs. You may want to test out some configuration changes but not cause any issues with the existing one that is used for production or maybe there is a new initiative, and you want to leverage what is in use today but customize it to the tests for the new initiative. Dashboards can be duplicated simply by using the upper right “...” options menu or ellipsis and selecting “Duplicate Dashboard” so you can test out and experiment with different configurations. See the screenshot below:

![Dashboard Duplication Options](/files/0WSC2DmqzLC2tD5HHQva)

* Click: **Duplicate Dashboard** and the Duplicate Dashboard pane will appear as shown below:

![Duplicate Dashboard Pane](/files/Qg9vEX7AmPTvmAHmUsRo)

* **Dashboard Name:** You must provide a unique name otherwise you won’t be able to save it.
* Click **Duplicate Dashboard**

## Dashboard Permissions and Tags

### Dashboard Permissions

If you want to set up your default dashboard when you log in so you aren’t automatically viewing the ThousandEyes Built-in one this can be accomplished provided you have the correct user access by clicking the **“...” options** menu or **ellipsis** pull down and selecting **Edit Dashboard** in the upper right corner of your dashboard as shown in the below screenshot:

![Edit Dashboard Pull Down Menu Option](/files/QFiZC32o8aUvGRmWPe2u)

This makes the **Dashboard Details Pane** appear; which can be used to modify different settings like labels, account groups, and default time range as shown in the below screenshot:

![Dashboard Details Pane](/files/6MqMJlVlZgm82QAFR5fK)

* **Account Group Visibility**: By default, this will be set to **Only current account group**. If you have other account groups that could benefit from your dashboard or want access to it you can share with all account groups or just specific ones using this selection.
* **View Settings**: Allows you to lock the dashboard down so it can only be visible to you. Which you may want to do while you are tuning or designing it or if it is something customized only for you. Additionally, you can set it as your default dashboard, and if you have the proper permissions set it as the account group default dashboard.
* Click the **Save Changes** button after you make changes to ensure they applied correctly.

### Dashboard Tags

Dashboard tags are a great way to quickly filter out a set of dashboards for troubleshooting. Some examples of ways to use them would be for dashboards that are for an application like Webex. You could have a dashboard dedicated to end-user experience using endpoint agents that your helpdesk uses, a dashboard showing Webex testing using enterprise agents for your branches and data center that your network and collaboration team use, and a dashboard with Internet Insights and Application Outages dedicated to Webex that everyone leverages. All these dashboards can share the same tag of Webex and when you select it, they will be filtered to make it faster to navigate between dashboards for troubleshooting issues. Following is an example of a Webex dashboard label that will show up when you click the dashboard selection pull-down list:

![Dashboard Labels Example](/files/WAYX7oIWGLjTETOQ9D2f)

* **Dashboards** pull down list
* **Custom Tags:** This example Webex is checked.
* **Manage** labels link

Another example could be that you have a critical business payment processing application with different layers of service, and you have enterprise agents monitoring from the inside to the edge which transits an internal load balancer, and externally have cloud agents monitoring it which transits an external load balancer. Additionally, there could be third party services that the application relies on, and different teams have their custom dashboards established to monitor the application internally versus externally versus the third party services. All the dashboards from these teams can be applied to the critical business payment application label allowing you to quickly filter and navigate between the different views.

To add a dashboard to a tag, click the **“...” options menu** or **ellipses** in the upper right corner of the dashboard view and click **Edit Dashboard**. The Dashboard Details pane will appear as shown in the below screenshot:

![Dashboard Details Pane](/files/M1Q1DK86YMs6vHqZjOJd)

* **Tag selection or Manage Tags:** You can associate your dashboard with an existing tag, if you have any, or use the manage tags link to create a tag.
* Click **Save Changes**

If you’d like to learn more about dashboard settings and customization refer to [Customizing Your Dashboard](https://docs.thousandeyes.com/product-documentation/dashboards/customizing-your-dashboard).

## Save or Download a Dashboard Snapshot

### Save a Dashboard Snapshot

Dashboard snapshots capture the data and all the metrics in the dashboard at that point in time and can be accessed in the future or shared with others, including in a ticket or chat so that the other person or team can see the same thing you are seeing. Click on the **camera icon** in the upper right on the dashboard page and it will create a drop-down list with a camera icon to **save a snapshot** of the dashboard as shown in the screenshot below:

![Dashboard - Save Snapshot](/files/ERyNVaxuIw5pK040Lbjc)

This opens the **Save a Snapshot** pane. It’s recommended to provide a meaningful name, so it can be referenced in the future. You will have to turn on link sharing to share it with others and copy the link otherwise it will only be available by logging into the ThousandEyes platform and viewing the snapshots directly in the **Manage > Sharing > Public Snapshots** menu. Following is an example of the Snapshot pane:

![Dashboard - Save Snapshot Options](/files/tPbc7b36fGzTislAhpv8)

* **Snapshot Name:** Provide a useful name for the snapshot for future reference like a ticket number for direct reference or information about the issue you’re troubleshooting and the date and time.
* **Link Sharing:** This is off by default, but you’ll need to toggle it to on in order to generate a unique link to the dashboard snapshot. **Note:** The link will not work untils you click the **Save and Share** button.
* **Copy button:** to copy the unique dashboard snapshot sharelink.
* **Save and Share:** This will save the dashboard snapshot and generate the sharelink which could take a few minutes.

### Download a Dashboard

You may want to quickly share a dashboard as a PDF or CSV with a coworker or other team which can be accomplished using the download icon as shown in the below image:

![Dashboard - Download](/files/RyTeWwMmNNoItX4Xk7GQ)

## Schedule a Dashboard Snapshot

Now that you have a compelling dashboard visualizing the key metrics, you can raise awareness of the network's health and the applications. Imagine a scenario, where a network manager has a weekly meeting with branch managers who blame the network for application slowness. You can create a scheduled snapshot, and email it to them before the meeting so they can see and share the network's health combined with the application response time.

To schedule a dashboard snapshot click the **camera icon** in the upper right corner of the dashboard view and select the **clock icon** labeled **Schedule A Snapshot** as shown in the below screenshot:

![Dashboard - Schedule Snapshot](/files/vu2VdZoHzXQiD33LL1JT)

The Schedule Snapshots pane will appear as shown in the below screenshot. Feel free to experiment with different options.

![Dashboard - Schedule Snapshot Options](/files/AUlLbk4lBPyvapWR79Pk)

* **Snapshot Name:** Be sure to use a name that will be useful for the intended recipients.
* **Repeat Interval:** This will be how often the snapshot is created and sent out or saved.
* **Emails:** By default, this will show the email addresses of the users that are configured to access the ThousandEyes platform in your account group. If you need to configure the email to go to someone that doesn’t show up in the list, click the Edit Emails link and you can add them to the list.
* Click **Done**

To learn about other features with sharing dashboards and scheduling reports you can refer to [Dashboard Sharing and Snapshots](https://docs.thousandeyes.com/product-documentation/dashboards/dashboard-shares-snapshots).


# Getting Started with Alerts

Alerting is a critical component of the ThousandEyes platform to inform operations teams of performance deviations or problems. From DNS availability to BGP reachability to layer-3 network metrics, ThousandEyes has a wide array of alert triggers. Learn how to use the alerting framework to your advantage by selecting the best [alert rule](https://docs.thousandeyes.com/product-documentation/getting-started/thousandeyes-glossary#alert-rule), customizing rule conditions and receiving notifications.

This getting-started guide will cover

* Creating alerts for your most important monitoring use cases.
* Baselining and customizing modular alert rules.
* Configuring notifications and alert integrations.

## Prerequisites

You should already have at least one periodically running test set up, testing against a specific endpoint or service. If you don’t have this set up, see [Getting Started with Tests](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-tests). Additionally, to get the most out of this guide, we recommend you read the following before you continue:

* [Getting Started with Global Vantage Points](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-global-vantage-points)
* [Getting Started with Enterprise Agents](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-enterprise-agents)
* [Getting Started with Network & App Synthetics Tests](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-cloud-and-enterprise-agent-tests)

## Key Topics

* [Alerts Overview](#alerts-overview)
* [Start with a Test](#start-with-a-test)
* [Create a Baseline Dashboard](#create-a-baseline-dashboard)
* [Create a Useful Alert Rule](#create-a-useful-alert-rule)
* [Configure Alert Notifications](#configure-alert-notifications)
* [Viewing and Working with Alerts](#viewing-active-alerts)
* [Tune Your Alert Rule](#tune-your-alert-rule)

## Alerts Overview

### Alerts' Relationship with Tests

Tests and alert rules have a many-to-many relationship. You can assign one or more alert rules to a single test; and you can also create a common set of alert rules and then assign them to a single test or to groups of tests.

Alert rules can be managed through the test settings interface or the alert rules interface. To view existing alert rules, go to **Alerts > Alert Rules**.

### Parts of an Alert Rule

Each alert rule has two components: the [conditions](#trigger-conditions) that must be met to trigger an alert; and a [notification policy](#notification-policy) that specifies how you want to be notified about alerting events.

#### Trigger Conditions

There are a number of ways to manage the conditions under which an alert rule will trigger. All alert rule types include these basic conditions:

* Threshold/s
* Number of agents required to meet the threshold
* Number of rounds or intervals across which those agents have to meet that threshold

#### Notification Policy

Alert notifications can be sent from the ThousandEyes platform via:

* Email
* Webhooks: An API-based integration with a platform of your choice. Preset configurations are available for tools such as Webex and Microsoft Teams.
* Built-in alert integrations with third-party platforms like PagerDuty and ServiceNow

### Types of Alert Rules

Alert rules are grouped into categories based on the application or network layer and source of the test. The categories of alert rules are:

* Network & App Synthetics
* Endpoint Experience
* Connected Devices
* BGP Routing
* Device
* Internet Insights

This guide focuses on alerting on Network & App Synthetics-based tests. For information on alerting on Connected Devices, see [Alerts for Connected Devices](https://docs.thousandeyes.com/product-documentation/connected-devices/connected-devices-alerts).

### Default Alert Rules

Go to **Manage > Alert Rules** to see your current list of rules. In the list of alert rules, the ones starting with "Default" are default rules that ThousandEyes automatically adds to tests. The **Apply To** column indicates how many tests are applied to the rule.

Because our example HTTP server test runs on Cloud Agents, for this getting-started guide you'll configure alert rules for this test using the **Network & App Synthetics** tab.

Check out the default alert rules associated with this test type. For HTTP server tests, ThousandEyes automatically enables a "Default HTTP Server 2.0" alert rule and a "Default Network 2.0" alert rule. The blue checkbox in the righthand column indicates that this alert rule is being assigned automatically to HTTP server tests.

![Alert Default HTTP Server 2.0 Example](/files/MP8UV4g7QjHMDg7wz20j)

For a full list of default rules, see [Default Alert Rules](https://docs.thousandeyes.com/product-documentation/alerts/default-alert-rules).

## Start with a Test

Tailoring your alert rule to hit exactly the right conditions ensures you have the right amount of alerts coming in without getting too many false positives. To get started, use a test to establish a baseline metric.

This guide uses an HTTP server test to monitor total round-trip times for a customer-facing website. You can use the test you created in the [Getting Started with Network & App Synthetics Tests](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-cloud-and-enterprise-agent-tests#configuring-test-settings) or use an existing one that you have configured in your environment. The best practice is to set up tests using Cloud and Enterprise Agent locations based on where customers or users access the site.

For more information about HTTP server tests, see [Internet and WAN Monitoring Tests](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests#http-server-test).

To learn more about the HTTP Total Time metric as well as other available metrics, see [ThousandEyes Metrics: What Do Your Results Mean?](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests/thousandeyes-metrics-what-do-your-results-mean#http-server)

## Create a Baseline Dashboard

False alerts can result in alert fatigue or people ignoring events. Setting alert rule thresholds limits the conditions that can trigger an alert notification. To determine appropriate thresholds, establish a baseline for important metrics. Evaluating test results is the most accurate way to establish a metrics baseline.

Creating a dashboard is a quick and easy way to review test metrics in order to establish a baseline. Using the HTTP server test from the previous section with a dashboard can help to establish the maximum acceptable round-trip time for website availability. Setting this value too low could produce too many alerts, while setting it too high could result in missed detection of service degradation.

The example dashboard pictured below uses an HTTP server test to determine the total round-trip time from a set of cloud agents to google.com. The following dashboard views use the HTTP Total Time metric:

* A timeline view showing the mean of the metric grouped by test
* A timeline view grouped by agents measured by 98th percentile
* A box and whiskers widget grouped by agent

![Baseline Dashboard](/files/LL8QG1raBEKg1kccmSDE)

All three views report HTTP total time from all agents over a 12-hour span. The top view, "HTTP Server Total Time (by Test)", reports that the average round-trip time from all agents is 120 ms.

The middle view, "HTTP Server Total Time (by Agent)", breaks the test data down by agent, providing more granularity. This view uses the 98th percentile of Total Time, rather than the mean, to show longer round-trip times that still fall within an acceptable level of service availability.

The bottom view, "Box and Whiskers (by Agent)", offers even greater precision. Also grouped by agent, this view shows the maximum, third quartile, median, first quartile, and minimum metric values. The Minneapolis threshold is reporting consistently below 200 ms, while The Dalles and Virginia locations are reporting below 100 ms.

Based on this analysis, a reasonable baseline for maximum acceptable HTTP total time is 200ms. Tests reporting a total round-trip time longer than 200ms, therefore, should trigger an alert. The next section covers configuring an alert rule using this threshold.

{% hint style="info" %}
Use the drill-down selection to include multiple tests in the widget. Show individual lines in the timeline view by using the **One Chart per Line** option for each test, or agent-based on the "group by" selection.
{% endhint %}

For information on creating dashboards, see [Getting Started with Dashboards](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-dashboards).

## Create a Useful Alert Rule

Custom alert rules allow for more accurate alerting that is more likely to reflect real impacts to service quality. Create a new custom alert rule for your example HTTP server test, using the [baseline metric analysis](#create-a-baseline-dashboard) you performed earlier.

To configure a new alert rule, navigate to **Alerts > Alert Rules** and click **Add New Alert Rule**.

![Alert Rules List](/files/RIRMQRNpUcJDARnf4uZV)

For this example, configure the alert using the following values. Each field is explained in more detail below.

| **Alert Type**                                   | Choose the kind of test this alert applies to: (Test Layer, Test Type): Web, HTTP Server                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Rule Name**                                    | Name the rule. For example, "Google HTTP Server Total Time"                                                                                                                                                                                                                                                                                                                                                                                                              |
| **Tests**                                        | Select the test to apply this rule to. This example uses "Google HTTP Server Test".                                                                                                                                                                                                                                                                                                                                                                                      |
| **Severity**                                     | This field indicates how critical it is to respond to the alert. The default for this field is "Info". For this example, set to "Minor". For more information on severity, see [Alert Severity](https://docs.thousandeyes.com/product-documentation/alerts/creating-and-editing-alert-rules/alert-severity).                                                                                                                                                             |
| **Alert Conditions**                             | The number of agents that must meet the alert rule's conditions in order to trigger an alert. For this example, set this field to: All conditions are met by "*any of*" "*1*" "*agent*" "*3*" of "*3*" times in a row. For more details on defining agent thresholds for alert conditions, see [Global and Location Alert Conditions](https://docs.thousandeyes.com/product-documentation/alerts/creating-and-editing-alert-rules/global-and-location-alert-conditions). |
| *Note: use "+" to create additional conditions.* | Create a condition using the test metric and the baseline value determined from the analysis in the previous section. Set to: "*Total Time*" "*>=*" "*Static*" "*200*" ms. For more information about alert rule operators and metrics, see: [Available Metrics Operators and Units](https://docs.thousandeyes.com/product-documentation/alerts/creating-and-editing-alert-rules#available-metrics-operators-and-units).                                                 |
|                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

Click **Create New Alert Rule** to save the alert rule.

![Custom Alert](/files/oW0flcKYsLeq7Bxule5U)

The alert rule created in this example has a `Minor` severity and will be triggered when the `HTTP Total Time` exceeds or equals 200 ms by any agent 3 out of 3 times in a row. Because this test has been configured to run every 2 minutes, after 6 minutes the alert will be triggered if any single agent's `HTTP Total Time` reports over 200 ms for 3 consecutive tests.

For more information on creating alert rules, see [Creating and Editing Alert Rules](https://docs.thousandeyes.com/product-documentation/alerts/creating-and-editing-alert-rules).

## Configure Alert Notifications

Alert notifications can be sent using email as well as to third-party solutions such as AppDynamics, PagerDuty, Splunk, Slack, and ServiceNow. For this guide we'll create an email notification. For information on third-party and custom webhook integrations, see [Next Steps](#next-steps).

### Send Alerts via Email

1. Expand the Google HTTP Total Time alert rule you previously created, so that you can edit it.
2. On the **Notifications** tab, click the drop-down arrow for the **Send emails to** field.
3. Type or select the email addresses of users who should receive ThousandEyes alert notifications.

   For example, a NOC distribution list or an SRE team.
4. If the email addresses you want to use aren't present in the drop-down list, click **Edit external emails** to add them.
5. \[Optional] Click **Add message** to customize the body of the email message users will receive

   For example, the email body might offer contact information or instructions on how to resolve the issue that activated the alert.

![Setting alert notifications to email](/files/Kox1PSp4PDoUxu2lq9ft)

By default, email notifications are sent only when an alert is first triggered. To receive an email when the alert clears, check the checkbox below the **Send emails to** field. Note that alerts in the dashboard remain active as long as the triggering rule criteria are met.

![Alert Clear Email](/files/sP4xnzBrItYZyoxSx61y)

For more information on alert notifications, see [Alert Notifications](https://docs.thousandeyes.com/product-documentation/alerts/alert-notifications).

## Viewing Active Alerts

Use the [active alert](https://docs.thousandeyes.com/product-documentation/getting-started/thousandeyes-glossary#active-alert) list to evaluate your alert thresholds, verify alert severity, and ensure that the proper agents are associated with an alert rule.

You can see a list of alerts in various ways in the ThousandEyes platform:

* In a dashboard: The **Alert List** dashboard widget shows all active alerts.
* On the **Alerts > Alert List** screen: Use this screen to see detailed reports on specific alerts.

In order to intentionally trigger an alert using the Google HTTP Test example from previous sections, modify the alert condition for total time by setting it to a lower value than what is typically reported in the tests. If the current threshold for total time is 200 ms, try setting it to 10 ms to trigger an alert. You can follow the same steps from [Create a Useful Alert Rule](#create-a-useful-alert-rule) to update the total time alert condition.

![Active Alert List](/files/Ke70HChONC1KhyyIXbPe)

1. View active alerts by clicking **Alerts > Alert List**.
2. Use the search box to find specific alerts using the `Alert ID` or `Name` of the alert. For this example, type the word “google” into the search box.
3. The listed alert reports the alert rule that was triggered, start time, scope, test name, and severity. Click on the small triangle to the left of the alert rule to expand an active alert. This expanded view shows the agents and related metrics to indicate why the alert was triggered.
4. Click the stack icon to the left of an agent's name to drill into individual test results for a specific agent. The test results offer a timeline view of the alert activity.

For more information, see [Viewing Alerts](https://docs.thousandeyes.com/product-documentation/alerts/viewing-alerts).

### Alert Clearing

An alert is considered [*cleared*](https://docs.thousandeyes.com/product-documentation/getting-started/thousandeyes-glossary#cleared-alert) when the conditions triggering it are no longer in effect. For alerts assigned to multiple locations, an alert will be cleared only when all locations no longer meet the alert conditions. This means that even if the alert conditions specify a minimum number of locations for the alert to be triggered, the alert will not clear until all locations no longer meet the alert conditions.

If an agent is unable to send data to the platform after becoming associated with an alert, the platform is able to auto-clear the alert after 12 hours of recieving no data from the active agent. To clear an alert manually, un-assign the alert rule from the test. Do this as you continue to refine alert rules to match your specific criteria.

For more information on alert clearing, see [Alert Clearing](https://docs.thousandeyes.com/product-documentation/alerts/alert-clearing).

### Analyzing Alert History

By default, the ThousandEyes platform shows the last 90 days of alerts. To see your organization's alert history, go to **Alert > Alert List > Alerts History**. Use the search bar to quickly find alerts. Use the time filter to isolate alerts based on a particular time period. Filtering alerts this way can help you determine whether your alerts are configured properly to align with your monitoring goals, and can help you report on alerts associated with an outage or service interruption event.

![Alerts History](/files/OdoII0LeOsqVTffJfSEx)

For more information, see [Alerts History](https://docs.thousandeyes.com/product-documentation/alerts/viewing-alerts#alerts-history).

## Tune Your Alert Rule

Alert rule conditions are a powerful way to minimize extra alert noise by ensuring that alerts represent real service impacts. This section demonstrates an alternative to hard-coding a static number of agents, and shows how to configure multiple alert conditions.

Specifying a static number of agents may not be ideal for many real-world situations. Using a percentage is more flexible, especially if you have a large number of agents or you are frequently adding and removing agents.

1. Go to **Manage > Alert Rules** and select the Google HTTP Total Time example you previously created.
2. Under **Alert Conditions**, change `Any of 1 agent` to `5 % of agents`.
3. Click **Save Changes** to update the alert rule.

![Tuning your alert rule by specifying a percentage of agents that must meet the alert condition](/files/tuVmAkEI6AEJUHJX9NSs)

An alert rule also supports multiple conditions. Using additional conditions can help you minimize extra alert noise by ensuring that alerts represent real service impacts.

In the Google HTTP Total Time example, you can specify `HTTP Response Time` as a condition in addition to `HTTP Total Time`:

1. Click the **+** button to the right of the `Total Time` alert condition.
2. Set to `Response Time` `Static` `>=` `100` ms.
3. Click **Save Changes** to update the alert rule.

![Tuning your alert rule by specifying multiple alert conditions](/files/cAwSF4ceGbGaevBd4Xp4)

Configuring good tests is also an important step in effective alerting. For more information on configuring tests, see [Getting Started with Tests](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-tests)

## Next Steps

Monitoring alerts and managing alert thresholds is an ongoing process. Review alerts and alert rules regularly to make sure that the right alerts are triggered during service interruptions and the right stakeholders are consistently notified. Use the timeline view to make sure baselines continue to be accurate on a regular basis. Being proactive with alerts reduces false positives and increases trust in the alerts from ThousandEyes, encouraging quick and effective service restoration.

For more information on setting up alerts, see the following:

* [ThousandEyes Alerting Essentials Webinar](https://www.thousandeyes.com/resources/alerting-webinar)
* [Proactive BGP Alerting](https://www.thousandeyes.com/blog/proactive-bgp-alerting)
* [Alerting by Geography, Network, and Device](https://www.thousandeyes.com/blog/alerting-by-geography-network-and-device)
* [Alert Suppression Windows](https://docs.thousandeyes.com/product-documentation/alerts/alert-clearing/alert-suppression-windows)

For more information on third-party integrations and custom webhooks:

* Pre-configured built-in integrations with third-party solutions, see [Custom-Built Integrations](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-built-integrations)
* Configuring custom webhooks and supported templates, see [Custom Webhooks](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-webhooks)
* Example guides for custom webhooks for alerting into popular domains, see [Custom Webhook Examples](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-webhook-examples)

Continue your getting-started journey:

* [Getting Started with Dashboards](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-dashboards)
* [Getting Started with Transactions](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-transactions)
* [Getting Started with the ThousandEyes API](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-the-thousandeyes-api)


# Getting Started with Internet Insights

Internet Insights is a service that detects major, widespread network and application outages across the global Internet. In this guide, you will learn to:

* Identify and triage outages that are **not** caught by your own tests
* Add context around the outages that **are** caught by your tests
* Understand the historical reliability of one or more service providers

## Introduction

Why should you use Internet Insights? When a critical service is disrupted, it's common to wonder if you're the only one affected by the outage or if the issue is larger in scope or scale. Internet Insights gives you visibility into the networks and SaaS applications you depend on. Internet Insights is built upon ThousandEyes’ collective data set -- billions of probes across the Internet to websites, apps, and API endpoints every day -- combined with algorithmic outage detection to provide a macro-scale view into network and application outages. The intelligence derived from this data enables operations teams to quickly identify and resolve issues with providers using concrete Internet telemetry data.

### Prerequisites

* Read the [Internet Insights terminology](https://docs.thousandeyes.com/product-documentation/internet-insights/int-terminology) article
* (Optional) Read the [Getting Started with Network & App Synthetics Tests](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-cloud-and-enterprise-agent-tests) article.

To use Internet Insights, your organization must have purchased one or more *package licenses*. To check if your organization is licensed for Internet Insights, either:

* Navigate to the **Manage > Account Settings > Usage and Billing** page and see the **Internet Insights Package Licenses** in the **Plan Usage** section, or
* If your user account does not have permissions to view the **Usage and Billing** page, you can look for **Internet Insights** in your navigation menu.
  * If the **Internet Insights** menu item does not have any sub-items, then you currently do not have a license for Internet Insights.
  * If the **Internet Insights** menu item does contain sub-items, including **Overview**, **Views**, and **Catalog Settings**, then your organization is licensed for Internet Insights.

| **Without** Internet Insights Licenses                                                                                                                                                           | **With** Internet Insights Licenses                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p><img src="/files/ZynOd75E7vEeHvgfeFpg" alt="Internet Insights welcome screen for non-licensed organizations"><br><em>Internet Insights welcome screen for non-licensed organizations</em></p> | <p><img src="/files/ZzmIppTNeRioexK282i1" alt="Internet Insights welcome screen for licensed organizations"><br><em>Internet Insights welcome screen for licensed organizations</em></p> |

### Outage Causes

Internet Insights outages display as *outage events*. Outage events can have a variety of causes. Here are just a few examples:

* Failures of physical infrastructure, such as a major cable cut or loss of power at an internet exchange facility or a data center
* Failures of internet infrastructure due to configuration typos, unscheduled maintenance, or political interference
* Distributed denial-of-service (DDoS) attacks

### How Are Outages Recognized?

Internet Insights detects outage events by analyzing the network-layer and application-layer results of every test that is run from ThousandEyes Cloud Agents or Enterprise Agents.

* A **Network Outage** is triggered when a concentration of packet loss events is detected within a single network point of presence (PoP) within a short period of time.
* An **Application Outage** is triggered when some or all servers that belong to the same application are failing, such as the application not responding to requests or responding with failure status codes.

## Configuring Internet Insights

It's worth reading the entire article on [Configuring Internet Insights](https://docs.thousandeyes.com/product-documentation/internet-insights/int-config) – you'll learn about packages and providers, and how to choose among them based on your business requirements or on critical business services.

### Understanding the Catalog

The Internet Insights catalog is a collection of service *providers* grouped into *packages*, and categorized by geographic region and provider type. Each Internet Insights package license allows you to activate one package from the catalog. For example, if you host infrastructure or workloads in public cloud providers’ North American data centers, or you depend on services that are hosted in those environments, you should activate the North American IAAS Providers package for visibility and outage detection into AWS, Azure, GCP, and others. You can see the complete catalog and the currently activated packages from the **Internet Insights > Catalog Settings** page. To view the specific providers included within a package, click the row for that package in the **Active Packages** list. This opens the **Coverage Map** dialog which shows the providers and the locations where Internet Insights has visibility coverage.

![Catalog settings page displaying Active Packages tab](/files/3RdWxhMugibN9H83Z3r2)

{% hint style="info" %}

#### Provider Labels

Provider labels can be used to filter outages in the Internet Insights views, alert rules, and dashboard widgets. To create a provider label, navigate to the **Internet Insights > Catalog Settings > Labels** tab and click **Add New Label**. To learn more, read the [Provider Labels](https://docs.thousandeyes.com/product-documentation/internet-insights/int-provider-labels) article.
{% endhint %}

### Activating a Package

To start using Internet Insights, you’ll need to activate one or more packages. Without any active packages, you’ll still see limited data – but only for your own Network & App Synthetics tests. To effectively use the visualizations, dashboards, and alerts, ensure that you allocate all of your available licenses by activating packages in the catalog.

To activate a package for Internet Insights when you have available licenses for it:

1. Go to **Internet Insights > Catalog Settings** screen and click the **Packages** tab.
2. Verify that the **Available** counter shows one or more licenses.
3. Find the row with the package that you want to add.
4. In the **Included** column, click the **Active** slider to add the package.

To activate a package when you have no available licenses, you must first deactivate a package, then activate the desired package in its place. To deactivate an Internet Insights package:

1. Go to **Internet Insights > Catalog Settings** screen and click the **Packages** tab.
2. Find the row with the package that you want to remove.
3. In the **Included** column, click the **Active** slider to remove the package.

## Using Internet Insights

The following sections describe the functionality of Internet Insights screens at a high level. For complete details about these screens, see the [Internet Insights Screens](https://docs.thousandeyes.com/product-documentation/internet-insights/int-screens) article and its sub-articles.

| The **Internet Insights > Overview** screen shows an overview of recent network outages (in red) and application outages (in purple). The default timespan is the last 24 hours, but can be configured as low as 15 minutes. This screen includes a timeline of the recent outages, a map visualization, and a summary and list of the outage events. Clicking on an outage will open the view for that specific outage in a new browser tab. | ![Overview screen displaying recent network outages](/files/FNCIQjhYCQcRXKkx114A)                    |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| On the **Internet Insights > Views** screen, choose either **Network Outages** (default) or **Application Outages**. If you clicked an outage event from the **Overview** screen to get to the **Views** screen, it will be set to the corresponding outage type.                                                                                                                                                                             | ![The Network Outages screen, showing a timeline for the past 24 hours](/files/jLPNmZ94GfHl8MxdFQ9V) |

### Network Outages

This section briefly describes the three tabs on the **Network Outages** view. See the [Network Outages](https://docs.thousandeyes.com/product-documentation/internet-insights/int-screens/int-network-outages) article for complete documentation.

| Topology tab                                                                            | Topology tab filters                                       |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| ![Topology tab highlighting affected nodes and interfaces](/files/4xcFhB88dYTIalFEicFA) | ![The Topology tab's filters](/files/sghVc2i6GggoochYrk9M) |

| Table tab                                                                                         | Map tab                                                                                                       |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| ![Table tab showing outages and a timeline when the outages occured](/files/tq33ww7wuxlmkYy0VINv) | ![Map tab displaying map of affected locations and specific details of each one](/files/u0bgdEXSsCMxQyJrVvso) |

For network outages, the **Internet Insights > Views > Topology** tab shows a network path visualization with traffic sources, target destinations, and the Internet hops between them. Sources are shown on the left, and destinations are shown on the right. The center of the visualization shows the interfaces where the outage is occurring. By default, interfaces are grouped by Autonomous System Number (ASN); click on the interface group in the topology visualization to drill down by location or IP address.

The short video clip below shows a network outage **Topology** tab, beginning with the default grouping and filters and then drilling down to the specific interfaces.

![Topology tab showing network path visualization details](/files/jU0XHXS0WGXTat2pBf2K)

### Application Outages

This section briefly describes the three tabs on the Application Outages view. See [Application Outages](https://docs.thousandeyes.com/product-documentation/internet-insights/int-screens/int-app-outages) for a complete description of the Application Outages screen.

* The **Topology** tab shows the flow from agents to the application. The application can be visualized by ASN, network prefix, location, or domain. Agents can be visualized by ASN or location. Use this tab to visualize the scope of the outage.
* The **Map** tab shows the geographical scope of the selected outage, along with summarized outage information.
* The **Table** tab includes detailed information on the types of application errors, as shown below.

| Topology tab                                                                                                    | Topology tab filters                                                                          |
| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| ![Topology tab showing flow between ThousandEyes agents and specific destinations](/files/EK787Ai4H8XiLvQpCY0m) | ![Topology tab filter option details](/files/Ajzs4T47GpliPOk57GS0)                            |
| Table tab                                                                                                       | Map tab                                                                                       |
| ![Table tab showing detailed information about outages](/files/aZuXFmBkdTkw9Lmgdwgo)                            | ![Map tab showing details of outages in specific areas on a map](/files/0Ezr5TB2KiyLxeijd5U3) |

## Workflows

The following sections describe some of the ways you can use Internet Insights, including:

* Outage detection and triage
* Adding detail to Internet Insights outages with Network & App Synthetics: “macro to micro"
* Adding context to Network & App Synthetics tests with Internet Insights: “micro to macro"

### Triaging an Outage from the Overview

Triaging is useful when you want to understand the impact and scope that an Internet outage is having on your organization. One common workflow is using Internet Insights for real-time outage detection and triaging. For example, some customers display the Internet Insights Overview screen on a large monitor in a 24/7/365 network operations center (NOC).

Navigate to **Internet Insights > Overview**. You should get started with the filters below and adjust them to fit your specific needs:

* **Outage Type**: All
* **Outage Scope**: All
* **Affected Provider**: All
* **Last 30 minutes**

The screenshot below of the **Overview** shows an outage that has occurred in the last few minutes. To begin triaging the outage, click on the provider name in the **Outage Events** column, or hover over the outage indicator on the map and click the provider name. This will open the **Network Outages** or **Application Outages** view based on the type of outage.

![Overview screen showing current outage events](/files/x4msaOxcvSC7l8FVonkQ)

In the view, scroll down to the **Topology** to quickly ascertain the scope and impact of the outage. First, consider the affected source locations (on the left of the topology) and affected destinations (on the right of the topology). If you do not have any stakeholders located in these areas and you do not depend on the affected services, then the outage likely has little to no impact on your operations.

If you do have users in the affected locations, and you depend on one or more of the affected services, then you should investigate the outage more closely. Hover over the affected interfaces (center of the topology) to show the outage details popover which indicates how many, if any, of your Network & App Synthetics tests are affected by this outage.

![Toplogy showing details of an affected interface](/files/NuzJjfQKEBBJ9sU6WIIl)

{% hint style="warning" %}
Be aware that the absence of affected tests does not necessarily mean the outage is not impacting you or your users. Unless you are certain you have created and enabled Network & App Synthetics tests that target the affected destination, you may have a gap in visibility, i.e, you have no tests which would have been affected by the outage.

If the affected destination is a critical service, or when the geographic scope is large, then the outage warrants deeper investigation. You may want to create new tests, or increase the frequency of existing tests, to ensure you have visibility coverage.
{% endhint %}

### Macro to Micro: Internet Insights to Network & App Synthetics Test View

Internet Insights, the “macro-level" view, provides context to outages, but less detail than individual Network & App Synthetics tests and their “micro-level" view. Starting from the Internet Insights view, when you do have one or more affected tests for a given outage, the destination nodes in the topology will display a small yellow circle. Hover over the destination node to see the specific tests.

| Network Outage Topology                                                                      | Application Outage Topology                                                                      |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| ![Network Outage Topology view of affected node outage details](/files/LqyYrUOcId0GOr5iiZbt) | ![Application Outage Topology showing details of outage at Twitter](/files/xnIbBXVvJWooVm8DmAa5) |

In the details popover, click the test name to open the test view in a new tab or window.

{% hint style="info" %}
You can also see affected tests, if any, in the **Map** and **Table** tabs.
{% endhint %}

When opening an affected test from a Network Outage view, the test view will default to the **Network > Path Visualization** layer. Look for these two key interface elements when viewing a test affected by an outage:

* The purple outage swimlane below the timeline, which indicates the specific test rounds in which the test was affected by an outage
* The **Outage Detected** button in the **Path Visualization** panel

![The timeline's outage swimlane and the path visualization display key information about an outage](/files/2cUn9jU98fEAFUam9xOv)

Click the **\[#] nodes** link inside the **Outage Detected** button to quickly highlight the nodes that are affected by the outage. Then look for the node(s) in the path visualization with a dashed red outline, like the one shown in the screenshot below.

Hover over the affected node and click the **Show only agents using the node** link to filter the path visualization and show only the agents which are affected. You can then hover over an agent and click **Show on timeline** to filter the timeline to the specific agent: this is useful for investigating any reductions in availability that may occur before and after a total service outage.

![Drilling down to get details about an affected node](/files/975OTvsaqUGhsy8XqGWV)

### Micro to Macro: Network & App Synthetics Test View to Internet Insights

Internet Insights can also be used to provide broader context to the precision-targeted Network & App Synthetics test results. When you are viewing a Network & App Synthetics test to investigate an issue, like a drop in application availability or an increase in network packet loss, you can quickly determine if the issue is affecting “just you" by looking for the purple swimlane below the timeline. In each test round that the purple swimlane is shown, it indicates that an outage has been detected which is affecting both this test and other tests from other ThousandEyes organizations.

The screenshot below shows an HTTP Server view, with the **Availability** metric selected on the timeline. In the middle of the timeline you can see a drop in server availability, and below the timeline, six purple bars are shown, indicating there was a broader outage affecting this test for six rounds.

![The HTTP server view, showing a drop in server availability](/files/DzcvoyJGsqXMMNAZWPp7)

To navigate from a Network & App Synthetics test view to the corresponding Internet Insights view, select a test round on the timeline which has a purple bar in the swimlane, then click **Path Visualization** in the **Views** menu to the left of the timeline.

In the **Path Visualization** panel, look for the **Outage Detected** button. Clicking on the button anywhere except the **\[#] nodes** link will display the outage details pop-up dialog.

![The Path Visualization panel, showing the outage details pop-up dialog](/files/H6v87w6p64NSfV7GV4Vq)

In the outage details pop-up dialog, click **Internet Insights Views** to open a new browser tab or window. The Internet Insights view will automatically be set to the appropriate outage type and filtered by the test from which the view was opened, as shown in the screenshot below.

![The Internet Insights Views screen](/files/wNprCPALU1Ob5CVGSGM6)

## Configuring Alerts and Dashboards

You can set up custom dashboards and alert rules for Internet Insights based on affected catalog providers or applications, including your own affected tests. The following two sections briefly describe how to configure alert rules and dashboard widgets using Internet Insights data. For more information, see the [Using Alerts and Dashboards with Internet Insights](https://docs.thousandeyes.com/product-documentation/internet-insights/using-alerts-and-dashboards-with-internet-insights) article.

### Internet Insights Alert Rules

To configure Internet Insights alert rules, navigate to the **Alerts > Alert Rules** screen, click the **Internet Insights** tab, and click **Add New Alert Rule**. Configure your settings and alert conditions in the dialog that opens, and click **Create New Alert Rule**. See the [Setting Up Alert Rules for Internet Insights](https://docs.thousandeyes.com/product-documentation/internet-insights/using-alerts-and-dashboards-with-internet-insights/setting-up-alert-rules-for-int) article for more information on Internet Insights alert rule settings and conditions.

![The Add New Alert Rule screen](/files/6l9pHe4lm8AB3G92BqQa)

### Internet Insights Dashboards

To view the Internet Insights includes a built-in dashboard, navigate to **Dashboards** and select **Internet Insights Built-in** from the **Dashboard:** dropdown selector. For more information on the built-in dashboard, see the [Using the Internet Insights Built-In Dashboard](https://docs.thousandeyes.com/product-documentation/internet-insights/using-alerts-and-dashboards-with-internet-insights/using-int-built-in-dashboard) article.

![The Internet Insights built-in dashboard](/files/H0LXY9IWV3TwA5ad1Omo)

You can also select Internet Insights as the data source for Data Summary widgets, Time Series widgets, and Map widgets on your custom dashboards. First, select your custom dashboard from the **Dashboard:** dropdown selector, or create a new custom dashboard by clicking the **Options** button and clicking **Create New Dashboard**.

With your custom dashboard open, click **+ Add Widget** at the top of the page and choose a widget in any of the Time Series, Data Summary, or Map categories. Select **Internet Insights** for the **Data Source**, and proceed to configure the widget based on your specific needs.

The screenshot below shows an example Map widget configuration using Internet Insights. To learn more about dashboards and dashboard widgets, see the [Getting Started with Dashboards](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-dashboards) guide and the [Dashboards](https://docs.thousandeyes.com/product-documentation/dashboards) section of the product documentation.

![Map widget configuration](/files/pqryp0RWvKnDXzr1mZiv)

## Next Steps

* Learn from a real Internet Insights outage analysis on the [ThousandEyes blog](https://www.thousandeyes.com/blog/aws-outage-analysis-july-28-2022)
* Watch the [Application Outages tutorial](https://www.thousandeyes.com/resources/internet-insights-application-outages-tutorial) video
* Review the [Internet Insights product documentation section](https://docs.thousandeyes.com/product-documentation/internet-insights)


# Getting Started with the ThousandEyes API

## Introduction

The ThousandEyes API enables programmatic access to ThousandEyes features and data, allowing you to integrate ThousandEyes with third-party systems and to automate tasks such as creating and modifying tests or retrieving test data. The ThousandEyes API is a RESTful API that uses standard HTTP methods and response codes.

In this guide, you will learn the basics of using the ThousandEyes API, including authentication and permission requirements, the different available endpoints, and example use cases with implementations.

More information on applicable terms and the complete developer reference is available at [ThousandEyes API v7 - Cisco DevNet.](https://developer.cisco.com/docs/thousandeyes/v7/)

### Prerequisites

To get the most out of this guide, you need the following prerequisites:

* A basic understanding of REST APIs and HTTP.
* Some familiarity with programming concepts and a programming language of your choice; or an HTTP client such as curl or Postman.

Because the ThousandEyes API enables you to interact with the entire ThousandEyes platform, we recommend that you complete the [Getting Started guides](https://docs.thousandeyes.com/product-documentation/getting-started) for the features and data you want to consume via the API.

* Account Administration and Management
  * [Getting Started with Account Setup](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-account-setup)
* Cloud and Enterprise Agents
  * [Getting Started with Enterprise Agents](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-enterprise-agents)
  * [Getting Started with Cloud and Enterprise Agent Tests](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-tests)
* Endpoint Agents
  * [Introduction to Endpoint Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents)
* Alerts
  * [Getting Started with Alerts](https://docs.thousandeyes.com/product-documentation/alerts)
* Dashboards
  * [Getting Started with Dashboards](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-dashboards)

### API User Requirements

To use the ThousandEyes API, you must have the following:

* Your user role must have the **API access** permission. The three built-in roles (Organization Admin, Account Admin, and Regular User) include this permission by default.
* You must have a [user API token](https://docs.thousandeyes.com/product-documentation/user-management/rbac#user-api-tokens) generated by the ThousandEyes platform to authenticate your requests.

### Authentication

The ThousandEyes API uses the HTTP bearer authentication scheme . Your API bearer token can be managed in **Account Settings > Users and Roles > Profile**.

{% hint style="info" %}
Tokens are only displayed when you create or re-create them. Ensure that you safely store your token (for example, in a password manager), as you will not be able to view the token again in the ThousandEyes platform after generating it. If you lose or forget your token, you can regenerate a new token in **Account Settings > Users and Roles > Profile**.
{% endhint %}

The OAuth bearer token allows you to authenticate to the ThousandEyes API using a token, without providing a username. To authenticate with your OAuth bearer token, you must include it in the `Authorization` header of your requests. The value of the header must be `Bearer <your-oauth-bearer-token-here>`.

The following example shows OAuth bearer token authentication with curl:

```
curl https://api.thousandeyes.com/v7/agents \
  --header "Authorization: Bearer $BEARER_TOKEN"
```

To authenticate in Postman with an OAuth bearer token:

1. In the **Authorization** tab, select the **Bearer token** type.
2. In the **Token** field, enter your OAuth bearer token.

![Postman screen for entering OAuth bearer token](/files/lFSYwlgeIai2qWuT4mFo)

## Making Requests

To use the ThousandEyes API, send an HTTP request to an endpoint at api.thousandeyes.com. The URL for your request should be of the form `https://api.thousandeyes.com/[version]/[endpoint]`. The current production version of the API is v7.

Before exploring the capabilities of the various endpoints, read the following sections on specifying an account group.

### Specifying an Account Group

API requests are handled within the context of an account group. If your user is assigned to only one account group, you do not need to specify an account group in your requests.

If your user is assigned to multiple account groups, the default account group context is your [login account group](https://docs.thousandeyes.com/product-documentation/user-management/rbac#login-account-group). To access a different account group, you must specify the account group ID in your API request by using the `aid` URL query parameter.

In the two example curl commands below, the first returns a list of all tests in the login account group, and the second returns a list of all tests in the account group with ID 123456. Note: For the sake of brevity, authentication is omitted from this example.

```
curl https://api.thousandeyes.com/v7/tests

curl https://api.thousandeyes.com/v7/tests?aid=123456
```

## API Endpoints and Use Cases

### Administrative and Account Management

One common use case of the ThousandEyes API is for managing your account groups and users. For example, you can easily create users in bulk, reassign users to different account groups, or programmatically create a new role and assign it to multiple users.

| Action/Method     | Account Groups                                                                                       | Users                                                                              | Roles                                                                              |
| ----------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Create (`POST`)   | [/v7/account-groups](https://developer.cisco.com/docs/thousandeyes/v7/#!create-account-group)        | [/v7/users](https://developer.cisco.com/docs/thousandeyes/v7/#!create-user)        | [/v7/roles](https://developer.cisco.com/docs/thousandeyes/v7/#!create-role)        |
| List (`GET`)      | [/v7/account-groups](https://developer.cisco.com/docs/thousandeyes/v7/#!list-account-groups)         | [/v7/users](https://developer.cisco.com/docs/thousandeyes/v7/#!list-users)         | [/v7/roles](https://developer.cisco.com/docs/thousandeyes/v7/#!list-roles)         |
| Details (`GET`)   | [/v7/account-groups/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-account-group) | [/v7/users/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-user) | [/v7/roles/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-role) |
| Update (`PUT`)    | [/v7/account-groups/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-account-group)   | [/v7/users/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-user)   | [/v7/roles/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-role)   |
| Delete (`DELETE`) | [/v7/account-groups/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-account-group)   | [/v7/users/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-user)   | [/v7/roles/{id}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-role)   |

### Cloud and Enterprise Agents

You can use the ThousandEyes API for managing your Cloud and Enterprise Agents and tests, and for retrieving test result data.

#### Configuration and Management

| Action/Method     | Tests                                                                                                           | Agents                                                                                                         |
| ----------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Create (`POST`)   | [/v7/tests/{testType}](https://developer.cisco.com/docs/thousandeyes/v7/#!create-agent-to-server-test)          |                                                                                                                |
| List (`GET`)      | [/v7/tests](https://developer.cisco.com/docs/thousandeyes/v7/#!list-configured-tests)                           | [/v7/agents](https://developer.cisco.com/docs/thousandeyes/v7/#!list-cloud-and-enterprise-agents)              |
| Details (`GET`)   | [/v7/tests/{testType}/{testId}](https://developer.cisco.com/docs/thousandeyes/v7/#!get-agent-to-server-test)    | [/v7/agents/{agentId}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-cloud-and-enterprise-agent) |
| Update (`PUT`)    | [/v7/tests/{testType}/{testId}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-agent-to-server-test) | [/v7/agents/{agentId}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-enterprise-agent)             |
| Delete (`DELETE`) | [/v7/tests/{testType}/{testId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-agent-to-server-test) | [/v7/agents/{agentId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-enterprise-agent)             |

#### Test Data

As described in [Getting Started with Tests](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-tests), most Cloud and Enterprise Agent tests are composed of multiple layers. Using the API, you can retrieve test data from the individual layers that comprise the test.

The complete list of endpoints for Cloud and Enterprise Agent test data is available in the [**Test Data**](https://developer.cisco.com/docs/thousandeyes/v7/#!test-results-api-overview) page of the developer reference. Using these endpoints, you can retrieve metrics from the following test layers:

* **Routing - BGP**: BGP metrics, BGP routes
* **Network**: End-to-end (“overview”), path visualization, and detailed path trace
* **Web**: FTP server, HTTP server, page load and waterfall, transaction and waterfall
* **DNS**: DNS server, DNS trace, DNSSEC
* **Voice**: SIP server, RTP stream

### Endpoint Agents

Use the Endpoint Agent APIs to manage your fleet of agents and configure your scheduled tests and dynamic tests.

#### Configuration and Management

| Action/Method     | Endpoint Agents                                                                                             | Scheduled Tests                                                                                                                                             | Dynamic Tests                                                                                                                                      |
| ----------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create (`POST`)   |                                                                                                             | [/v7/endpoint/tests/scheduled-tests/{testType}](https://developer.cisco.com/docs/thousandeyes/v7/#!creates-agent-to-server-endpoint-scheduled-test)         | [/v7/endpoint/tests/dynamic-tests/agent-to-server](https://developer.cisco.com/docs/thousandeyes/v7/#!create-endpoint-dynamic-test)                |
| List (`GET`)      | [/v7/endpoint/agents](https://developer.cisco.com/docs/thousandeyes/v7/#!list-endpoint-agents)              | [/v7/endpoint/tests/scheduled-tests](https://developer.cisco.com/docs/thousandeyes/v7/#!list-endpoint-scheduled-tests-list-endpoint-scheduled-tests)        | [/v7/endpoint/tests/dynamic-tests/agent-to-server](https://developer.cisco.com/docs/thousandeyes/v7/#!list-endpoint-dynamic-tests)                 |
| Details (`GET`)   | [/v7/endpoint/agents/{agentId}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-endpoint-agent) | [/v7/endpoint/tests/scheduled-tests/{testType}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-agent-to-server-endpoint-scheduled-test)        | [/v7/endpoint/tests/dynamic-tests/agent-to-sever/{testId}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-endpoint-dynamic-test)      |
| Update (`PATCH`)  | [/v7/endpoint/agents/{agentId}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-endpoint-agent)   | [/v7/endpoint/tests/scheduled-tests/{testType}/{testId}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-agent-to-server-endpoint-scheduled-test) | [/v7/endpoint/tests/dynamic-tests/agent-to-sever/{testId}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-agent-to-server-dynamic-test) |
| Delete (`DELETE`) | [/v7/endpoint/agents/{agentId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-endpoint-agent)   | [/v7/endpoint/tests/scheduled-tests/{testType}/{testId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-agent-to-server-scheduled-test)          | [/v7/endpoint/tests/dynamic-tests/agent-to-sever/{testId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-agent-to-server-dynamic-test) |

#### Test, Network, and Session Data

As described in the [Endpoint Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents) article, ThousandEyes Endpoint Agents collect measurements in multiple ways: scheduled synthetic tests, dynamic tests, real user tests sessions, and local network topology. You can use the ThousandEyes API to retrieve Endpoint Agent data from each of these areas; see the [**Endpoint Test Results**](https://developer.cisco.com/docs/thousandeyes/v7/#!endpoint-test-results-api-overview) page in the developer reference.

* **Scheduled Test Data**: HTTP server, network end-to-end, path visualization, and detailed path trace
* **Dynamic Test Data**: Network end-to-end, path visualization, and detailed path trace
* **Real User Test Data**: Real user test list and details, visited page list and details, network sessions list
* **Local Network Data**: Network topology list and details

### Alerts

You can use the API to retrieve the list of all active alerts and the details for individual alerts. You can also manage your alert rules and alert suppression windows.

| Action/Method   | Alerts                                                                                            | Alert Rules                                                                                         | Alert Suppression Windows                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Create (`POST`) |                                                                                                   | [/v7/alerts/rules](https://developer.cisco.com/docs/thousandeyes/v7/#!create-alert-rule)            | [/v7/alert-suppression-windows](https://developer.cisco.com/docs/thousandeyes/v7/#!create-alert-suppression-window)              |
| List (`GET`)    | [/v7/alerts](https://developer.cisco.com/docs/thousandeyes/list-alerts/)                          | [/v7/alerts/rules](https://developer.cisco.com/docs/thousandeyes/v7/#!list-alert-rules)             | [/v7/alert-suppression-windows](https://developer.cisco.com/docs/thousandeyes/v7/#!list-alert-suppression-windows)               |
| Details (`GET`) | [/v7/alerts/{alertId}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-alert-details) | [/v7/alerts/rules/{ruleId}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-alert-rule) | [/v7/alert-suppression-windows/{windowId}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-alert-suppression-window) |
| Update (`PUT`)  |                                                                                                   | [/v7/alerts/rules/{ruleId}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-alert-rule)   | [/v7/alert-suppression-windows/{windowId}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-alert-suppression-window)   |
| Delete (`POST`) |                                                                                                   | [/v7/alerts/rules/{ruleId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-alert-rule)   | [/v7/alert-suppression-windows/{windowId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-alert-suppression-window)   |

### Dashboards

| Action/Method     | Dashboard                                                                                             | Dashboard Snapshot                                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Create (`POST`)   | [/v7/dashboards](https://developer.cisco.com/docs/thousandeyes/v7/#!create-dashboard)                 | [/v7/dashboard-snapshots](https://developer.cisco.com/docs/thousandeyes/v7/#!create-dashboard-snapshot)                |
| List (`GET`)      | [/v7/dashboards](https://developer.cisco.com/docs/thousandeyes/v7/#!list-dashboards)                  | [/v7/dashboard-snapshots](https://developer.cisco.com/docs/thousandeyes/v7/#!list-dashboard-snapshots)                 |
| Details (`GET`)   | [/v7/dashboards/{dashboardId}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-dashboard) | [/v7/dashboard-snapshots/{snapshotId}](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-dashboard-snapshot) |
| Update (`PUT`)    | [/v7/dashboards/{dashboardId}](https://developer.cisco.com/docs/thousandeyes/v7/#!update-dashboard)   |                                                                                                                        |
| Delete (`DELETE`) | [/v7/dashboards/{dashboardId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-dashboard)   | [/v7/dashboard-snapshots/{snapshotId}](https://developer.cisco.com/docs/thousandeyes/v7/#!delete-dashboard-snapshot)   |

You can also retrieve the data for a dashboard widget using the [retrieve dashboard widget data](https://developer.cisco.com/docs/thousandeyes/v7/#!retrieve-dashboard-widget-data) endpoint.

## Example Code Snippets

One of the advantages of a RESTful API is its flexibility and versatility. A well-designed API allows developers to integrate it into their applications in many different ways, depending on their specific needs and requirements. This section provides a few examples of how you might use the ThousandEyes API, to give you an idea of its potential applications.

It's important to note that the examples provided below are only a small subset of the many ways you could use this API. Your particular use case may be quite different from those described, but these examples will help you understand the possibilities and inspire you to create your own integrations.

Additionally, please be aware that the code implementations provided below are strictly examples and are not intended for production use. They may not follow best practices, and may not be optimized for performance or security. They are simply meant to illustrate how you might interact with the ThousandEyes API in a particular context.

With that in mind, let's dive into some examples of how you might use this ThousandEyes API in practice.

### Getting a List of Cloud Agent IPs for Automating Firewall Rules

Cloud Agents are generally used to monitor public internet-facing web applications, but occasionally you may test a target that only allows traffic from explicitly allowed sources. In this case, you need to add the Cloud Agents' IP addresses to your security rule access control list, to allow the test traffic to reach the target server. Using the ThousandEyes API, you can easily retrieve the IP addresses for any Cloud Agents so that you can add them to your allow-list.

This example uses two CLI utilities, curl and [jq](https://stedolan.github.io/jq/), to request and parse the list of agents and their respective IP addresses. Additionally, this example demonstrates that you do not need programming knowledge to interact with the ThousandEyes API.

First, use curl to make a request to the `/v7/agents` endpoint and write the response to a file:

```bash
curl -o agents.json https://api.thousandeyes.com/v7/agents \
          -H "Authorization: Bearer $BEARER_TOKEN"
```

This will create a file named **agents.json** in the current working directory where you ran the curl command. The file contains a JSON object with a key named `agents` mapped to a list of objects representing the agents, like the excerpt below:

```json
{
    "agents": [
    {
        "agentId": 3,
        "agentName": "Singapore",
        "agentType": "Cloud",
        "countryId": "SG",
        "targetOnly": 0,
        "ipAddresses": [
            "64.29.136.162",
            "64.29.136.173",
             ...
           ]
        }
  ]
}
```

Now that you have retrieved the agent data from the ThousandEyes API, you can parse or post-process it to meet your requirements. For example, you can use the jq utility to read the **agents.json** file and extract three fields: the agent ID, the agent name, and the agent’s IP addresses.

```bash
jq -r '.agents[] | [.agentId, .agentName, .ipAddresses|tostring] ' agents.json
```

The output from the jq command should look something like this:

```json
[
   "3",
   "Singapore",
   "[\"64.29.136.162\",\"64.29.136.173\", ...]"
]
```

You can also use jq to filter the response. For example, you can include only specific agents in the output:

```bash
jq -r '.agents[] | select (.agentName | IN("Singapore", "Boston, MA")) | [.agentId, .agentName, .ipAddresses|tostring] ' agents.json
```

Or, you can use jq to format the JSON as a CSV file, like so:

```bash
jq -r '.agents[] | [.agentId, .agentName, .ipAddresses|tostring] | @csv ' agents.json > agents.csv
```

### Exporting Test Data to a CSV File

Retrieving test data is a common use case for the ThousandEyes API. For example, you may want to perform some data analysis on the test results in the tool of your choice, or you need to archive test data longer than the ThousandEyes platform data retention provides, or you collect and aggregate all of your observability data in a centralized data store.

The following code snippet shows how to request, parse, and output the network latency for all agents in a single test over the last one hour. This example uses the Python programming language and the open-source [`requests`](https://requests.readthedocs.io/en/latest/) package for making HTTP requests to the API server, but you may use whatever language and HTTP client package you prefer.

```python
# Import standard modules
import csv
import json
  
# Import third-party HTTP client package
import requests
  
### Define HTTP request values
OAUTH_BEARER_TOKEN = "YOUR-OAUTH-BEARER-TOKEN-HERE"
TEST_ID = 123456

# Make the HTTP request to the /v7/test-results/{testId}/network endpoint, including
# the Oauth bearer token and specifying the response must be JSON format
resp = requests.get(
  f"https://api.thousandeyes.com/v7/test-results/{TEST_ID}/network?window=60m",
  headers={"Authorization": f"Bearer {OAUTH_BEARER_TOKEN}"},
)
resp_body = resp.json()

# Parse the response JSON to store the metrics by test round so we can
# later write each round as a row in the CSV file
agent_names = set()
data_by_round = {}
metrics = resp_body["results"]
for metric in metrics:
        if metric["roundId"] not in data_by_round:
                data_by_round[metric["roundId"]] = {}
        agent_names.add(metric["agent"]["agentName"])
        data_by_round[metric["roundId"]][metric["agent"]["agentName"]] = metric["avgLatency"]

# Write the data to a CSV file
agent_names = list(agent_names)
with open("test_data.csv", "w") as f:
        csv_file = csv.writer(f)
        csv_file.writerow(["Round ID", *agent_names])
        for roundId, metrics in data_by_round.items():
                csv_file.writerow([roundId, *[metrics[agent] for agent in agent_names]])
```

### Change the Interval of a Cloud and Enterprise Agent Test

The test configuration endpoints are useful whenever you need to create or re-configure a large number of tests, or when you integrate ThousandEyes with an automation pipeline such as Continuous Integration / Continuous Delivery. This example demonstrates how to programmatically re-configure a Cloud and Enterprise Agent test using the JavaScript programming language and the open-source [`node-fetch`](https://www.npmjs.com/package/node-fetch) package for making HTTP requests.

In the code snippet below, the testing interval of a given test is toggled between 10 minutes and 5 minutes. This could be useful for testing at different intervals at different times of day - for example, more frequently during business hours and less frequently during inactive times. It could also be used as the receiver of an alert rule webhook: if a given test triggers an alert, then increase the testing frequency to get more granular data.

First, an API call is made to get a test’s current configuration. Then the configuration is modified to change the test interval. Finally, another API call is made to update the test to use the new configuration:

```javascript
import fetch from 'node-fetch';

toggleTestInterval();

async function toggleTestInterval() {
   // Define HTTP request values
   const oauth_bearer_token = "YOUR-OAUTH-BEARER-TOKEN-HERE"
   const test_id = 123456;

   // Get the current test configuration
   let resp = await fetch(`https://api.thousandeyes.com/v7/tests/web-transactions/${test_id}`, {
       headers: {'Authorization': `Bearer ${oauth_bearer_token}`}
   });
   let body = await resp.json();
   let test_config = body;

   // Toggle the interval between 600 seconds and 300 seconds
   test_config['interval'] = test_config['interval'] == 600 ? 300 : 600;

   // Delete read-only fields from the test configuration before making the call to update
   delete test_config.testId;
   delete test_config.savedEvent;

   // Call the API to update the test configuration using the new interval
   resp = await fetch(`https://api.thousandeyes.com/v7/tests/${test_config['type']}/${test_id}`, {
       headers: {
           'Authorization': `Bearer ${oauth_bearer_token}`,
           'Content-Type': 'application/json'},
       method: 'PUT',
       body: JSON.stringify(test_config)
   });
};
```

## Next Steps

Review the [ThousandEyes API v7 Reference](https://developer.cisco.com/docs/thousandeyes/v7/#!account-group-context) for more details on API endpoints and request/response characteristics, such as:

* Time spans
* Pagination
* Rate limiting

Watch the [Short & Sweet into ThousandEyes API Suite](https://www.ciscolive.com/on-demand/on-demand-library.html?search=thousandeyes#/session/1675722384027001tnDb) on-demand breakout session from Cisco Live Amsterdam 2023. If you use Postman as your HTTP client, you should [import the ThousandEyes Postman Collection](https://www.postman.com/cisco/cisco-devnet-s-public-workspace/collection/v2ogbsf/cisco-thousandeyes-api-v7?ctx=documentation).


# Getting Started with the ThousandEyes MCP Server

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. It provides a standardized interface for AI models to interact with your systems, making integrations portable across different AI platforms.

The ThousandEyes MCP server connects AI tools to your ThousandEyes infrastructure, enabling natural language interactions with your network monitoring data. You can ask questions, run diagnostics, analyze performance, and automate workflows through conversation.

By integrating ThousandEyes with your AI assistant via MCP, you can:

* Use natural language queries instead of navigating the ThousandEyes platform UI or using API syntax.
* Leverage intelligent analysis where the AI understands networking concepts and interprets results.
* Chain multiple operations together in a single request.
* Generate executive summaries, technical deep dives, or incident postmortems.
* Get guided diagnostics and root cause analysis for faster troubleshooting.

### Prerequisites

To use the ThousandEyes MCP server, you need:

* The *API Access* ThousandEyes user permission. Any user with this permission can use the MCP server. For more information on user permissions, see [Role-Based Access Control](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control).
* A ThousandEyes API token. For instructions on generating a new API token, see [User API Tokens](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control#user-api-tokens).
* An MCP-compatible client, such as Claude, Cursor IDE, Microsoft CoPilot, AWS Kiro or Google Gemini. This getting started guide uses the ThousandEyes plugin for the Cursor IDE as the MCP-compatible client. For setup instructions for other supported clients, see the [ThousandEyes MCP Server integration guide](https://docs.thousandeyes.com/product-documentation/integration-guides/thousandeyes-mcp-server).

## Connecting to the ThousandEyes MCP Server

To install the Cisco ThousandEyes Cursor plugin:

1. Open the **Agent Chat** window in Cursor and type `/add-plugin ThousandEyes`, then press **Enter**.
2. A browser window will open with a log in prompt. Log in to your ThousandEyes Account.
3. After logging in, you will be prompted to approve sharing your DCR proxy token with the Cursor IDE. Click **Approve**.

By default, the ThousandEyes MCP tools will now be approved to run using your account permissions. To test the configuration, open the **Agent Chat** window and type: `What ThousandEyes MCP tools do I have access to?`, then press **Enter**.

## Usage

ThousandEyes MCP server usage counts against your API rate limit, but the specific limit depends on your authentication method:

* OAuth Bearer Token: Usage counts against your organization-wide rate limit (typically 240 requests per minute). This usage is shared with other integrations using standard API tokens. For more information, see [Rate Limits](https://developer.cisco.com/docs/thousandeyes/rate-limits/).
* OAuth 2.0 Access Token: Each OAuth2 client has its own separate rate limit of 240 requests per minute. This usage does not affect your organization-wide rate limit.

Unit Consumption for Instant Tests:

{% hint style="warning" %}
When asking the assistant to run an "Instant Test," the platform executes a live test that consumes units. The pricing is identical to scheduled tests, but is billed for a single round. For details, see [Configuration-Based Consumption Model](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/our-consumption-models/configuration-based-consumption-model).
{% endhint %}

## Capabilities

Once your AI assistant is connected to the ThousandEyes MCP server, you can use natural language to call various tools to manage tests, monitor alerts, and perform advanced analysis.

For a complete list of available tools, see [MCP Server Functionality and Sample Prompts](https://docs.thousandeyes.com/product-documentation/integration-guides/thousandeyes-mcp-server#mcp-server-functionality-and-sample-prompts).

Here are some examples of what you can ask your AI assistant:

**Troubleshooting**

* "Run an instant HTTP test to **URL** from **locations**."
  * Follow up: "Show me detailed results for instant test **test-id**, including response times, errors, and network path analysis. What failed?"
  * Follow up: "Show me all active failures in **account group** grouped by severity, with root cause analysis and impacted services."
* "Analyze AWS Bedrock API health across all monitored regions: availability, latency, error rates, and active alerts."
* "Customer complaints about slow checkout - show me all checkout/transaction tests with current performance vs baseline and identify bottlenecks."
* "Analyze **metric** trends for **test/service** over **timeframe**. Show baseline, current values, and statistical anomalies indicating degradation."
* "Compare **test/service** performance between **location A** and **location B**. Show latency, packet loss, and routing differences to identify optimal path."
* "What changed in **test/service** performance around **timestamp**? Show me before/after metrics."
* "Show me the network path from **location** to **target** with latency breakdown by hop."
* "Is there packet loss or high latency affecting **service** right now? Show me which agents are impacted."
* "Compare BGP routing for **prefix/service** across all monitors. Are there path changes?"

**Summarization**

* Executive summary: "Create an executive summary report outlining the health status of my monitored services and applications in **account group**? Show me availability, performance issues, and active incidents."
* Morning standup: "Show overall health for the **org/account group**."
* Weekly review: "Comprehensive monitoring report for last 7 days."

**Optimization**

* "Identify critical services and applications not currently monitored in **account group**, prioritized by business impact."
* "Show me blind spots in my monitoring coverage for **account group**. Which critical services have no tests, redundancy, or multi-vantage-point validation?"
* "Analyze response time baseline for **test name/ID** over the past **timeframe**. Correlate with triggered alerts, and recommend alert threshold optimizations for **account group**."
* "Are there any tests that haven't run successfully in the last week?"

## Best Practices

When writing prompts for your AI assistant, keep the following best practices in mind to get the most accurate and useful results:

* **Be specific about time ranges**: Instead of "Show me alerts from the last six hours", use "Show me critical alerts from 2pm-8pm EST yesterday".
* **Name what you want analyzed**: Instead of "Check test performance", use "Analyze HTTP response times for test 'Checkout Flow Production' over the past week".
* **Specify the output format**: Instead of "Get my test results", use "Get test results as a table showing test name, status, and average response time".
* **Chain operations logically**: Instead of "Find slow tests, then analyze them", use "Find all tests with >2s response time, run instant tests from five locations, compare with baseline, and create a performance report".

### Common Use Cases

* **Incident response**: "We are seeing elevated error rates on our API. Run diagnostics: check current alerts, get path visualization, run instant tests from key locations, analyze service dependencies, and create an incident summary with recommended actions."
* **Performance monitoring**: "Monitor my checkout flow: compare page load times week-over-week, identify bottlenecks, and alert me if any metric degrades by >20%."
* **Root cause analysis**: "Walk me through debugging this intermittent connectivity issue step by step."
* **SLA reporting**: "Calculate our uptime percentage for Q1 across all HTTP server tests."

## References and Additional Information

* [Optimize AIOps With the ThousandEyes MCP Server)](https://www.thousandeyes.com/blog/optimize-aiops-with-thousandeyes-mcp-server)
* [Cisco ThousandEyes AgenticOps: When AI Monitors AI via MCP](https://www.thousandeyes.com/blog/agentic-ops-when-ai-monitors-ai-via-mcp)
* [Beyond the Chatbot: Assuring AI-powered Customer Support With ThousandEyes](https://www.thousandeyes.com/blog/ai-support-assurance)
* [Monitoring AI Agents for Production Reliability](https://www.thousandeyes.com/blog/monitoring-ai-agents-production-reliability)


# Getting Started with ThousandEyes and Cisco Secure Access

This guide explains how to integrate ThousandEyes with Cisco Secure Access so you can monitor endpoint, application, and network performance in one workflow.

## Understanding the Integration

Hybrid work requires a modern security model, and Security Service Edge (SSE) is a key part of that model. SSE brings together cloud-delivered security functions to protect critical resources and support employees, contractors, and partners working from any location. Cisco Secure Access is a cloud-delivered, zero-trust SSE solution that helps secure access to SaaS applications, private applications, and the internet across private data centers and cloud environments. This approach helps you improve user simplicity and IT efficiency while protecting users, devices, and data against sophisticated and evolving threats, including AI-driven attacks and identity-based attacks.

Experience Insights in Cisco Secure Access uses ThousandEyes data to help your IT and security teams troubleshoot user experience issues faster. After onboarding is complete, your team can see endpoint visibility in Cisco Secure Access while continuing to use ThousandEyes for detailed test and agent workflows.

## Prerequisites

Before you start:

* Make sure you have an active ThousandEyes user with the **Organization Admin** role. For role details, see [Built-in Roles and Permissions](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control/built-in-roles-and-permissions).
  * ThousandEyes provides secure OAuth 2.0 integrations with Cisco Secure Access. For background information, see [OAuth Overview](https://docs.thousandeyes.com/product-documentation/user-management/authorization/oauth-overview).
* Use a dedicated service account for this integration so onboarding is not tied to one person.
* Verify the integration user belongs to the account group you plan to use. For account group details, see [What Is an Account Group?](https://docs.thousandeyes.com/product-documentation/user-management/authorization/account-groups/what-is-an-account-group).
* Make sure you have an active Cisco Secure Access account with administrator permissions.

## Licensing and Onboarding Flows

Cisco Secure Access includes an Embedded ThousandEyes Endpoint Agent license entitlement with:

* One dynamic test per Endpoint Agent.
* One scheduled test to monitor the connection path between the endpoint and Cisco Secure Access.
* Four-day retention for telemetry collected by these tests.

For complete license behavior and upgrade paths, see [Endpoint Agent Licensing](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/endpoint-agent-licensing).

### Onboarding Flow

After you purchase Cisco Secure Access, provisioning for ThousandEyes starts automatically:

* **New ThousandEyes organizations:** A new ThousandEyes organization is created and embedded licenses are provisioned. After the ThousandEyes organization has been provisioned, an email notification containing login instructions is sent to the designated organization administrator. By default, the ThousandEyes organization administrator is the same contact as the Cisco Secure Access administrator.
* **Existing ThousandEyes organizations:** Embedded licenses are provisioned into your existing organization.

By default, ThousandEyes organizations are provisioned in US regions. If your organization requires EU data residency, contact <support@thousandeyes.com> to request migration.

### Troubleshooting Provisioning

After ThousandEyes provisions your organization, ThousandEyes sends an email with login instructions to your designated organization administrator. By default, the ThousandEyes organization administrator is the same contact as your Cisco Secure Access administrator.

If that email does not arrive within 72 hours of Cisco Secure Access activation, or if embedded licenses do not appear in your ThousandEyes organization, open a case with Cisco TAC so the team can investigate and resolve the provisioning issue.

## Configuring the ThousandEyes Integration in Cisco Secure Access

1. In Cisco Secure Access, go to **Experience Insights** and select **Begin onboarding**.

![Experience Insights onboarding screen in Cisco Secure Access](/files/ZN9cPiDlny3zBtV3gQOo)

2. Select **Integrate** to launch the ThousandEyes authorization flow.
3. Sign in to the ThousandEyes platform with an **Organization Admin** account.
4. Approve the requested permissions for the integration.
5. Wait for the onboarding wizard to show a successful integration state, then select **Next**.
6. Choose your integration method:
   * **Default account group integration** creates two default tests within the default account group. Only Endpoint Agent data associated with this specific account group is imported and integrated with Cisco Secure Access.
   * **Multiple account groups integration** creates two default tests across all account groups. Endpoint Agent data from all account groups is imported and integrated with Cisco Secure Access.
7. Select the default test target that best matches your endpoint traffic model (for example, Zero Trust Access, RAVPN, or SWG Roaming Module).

![Default test target options for the Cisco Secure Access integration](/files/zrlCcFVfVh8uWEylrGSw)

8. Select your primary collaboration application (**Webex**, **Zoom**, **Microsoft Teams**, or **None**).

![Collaboration application options for the Cisco Secure Access integration](/files/OEPjpQzWWjJDpXDZAQCv)

9. Deploy Endpoint Agents in the selected account group so Experience Insights can ingest endpoint data.

## Installing and Registering the Endpoint Agent

The ThousandEyes Endpoint Agent is delivered as a Cisco Secure Client module and is not installed by default.

### Installation

For production rollouts, deploy the module through your endpoint management workflow (for example, Microsoft Intune) to keep configuration consistent across devices.

If you use Cisco Secure Client Cloud Management, you can deploy the ThousandEyes module to registered endpoints by applying policy from Cloud Management.

### Activation

When Cisco Secure Client starts an active ZTA, Roaming Module, or VPN session, the Endpoint Agent attempts to register automatically.

If the first registration attempt fails, the agent retries every 10 minutes in this order:

1. ZTA
2. Roaming Module
3. VPN

License consumption priority at initial registration is:

1. Advantage
2. Essentials
3. Embedded (included with Cisco Secure Access)

If the ThousandEyes organization contains only Embedded licenses, Endpoint Agents consume those licenses.

You can manually reassign licenses after installation. For details, see [Managing Endpoint Agent Licenses](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/endpoint-agent-licensing#managing-endpoint-agent-licenses).

![Endpoint Agent license details in the ThousandEyes platform](/files/ZI1bXwSzqK29VWpLM3d0)

## Managing Endpoint Agents

After agents are deployed and registered, use status automation, tags, and the ThousandEyes API to keep operations scalable.

### Status Management

Use automatic status management settings in **Endpoint Experience > Agent Settings** to manage inactive endpoints and recover licenses. For details, see [Manage Endpoint Agent Settings](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/managing/manage-endpoint-agent-settings#auto-manage-the-status-for-endpoint-agents).

### Creating Tags

You can organize agents using tags based on attributes such as location, department, or operating system. Tags also streamline agent selection for test assignments, simplifying filtering and reporting for large-scale deployments. For more information, see [Tags overview](https://docs.thousandeyes.com/product-documentation/tags/tags-overview).

### Using the Endpoint Agent API

Use the ThousandEyes API to manage Endpoint Agents at scale. For detailed information and reference, see the [Endpoint Agent API documentation](https://developer.cisco.com/docs/thousandeyes/endpoint-agents-api-overview/).

## Viewing Test Data

After integration and registration, Cisco Secure Access and ThousandEyes both provide views into endpoint performance.

These two tests are automatically created in ThousandEyes based on the configuration performed in steps 7 and 8 of the onboarding process.

In ThousandEyes, verify tests under **Endpoint Experience > Test Settings** and review results in:

![Endpoint Experience Test Settings screen for Cisco Secure Access tests](/files/yOPSuRkXqhgHGLCC0e6u)

* **Endpoint Experience > Agent Views** for endpoint-specific telemetry.

![Endpoint Experience Agent Views screen with endpoint telemetry](/files/pZwQXqwZmMh7wDnglsVO)

* **Endpoint Experience > Views** for test-centric and path-centric analysis.

![Endpoint Experience Views screen for test and path analysis](/files/SOLQYJGS6g5GQbbAdhiI)

In addition to scheduled and dynamic tests, Endpoint Agents continuously collect local telemetry such as DNS latency, packet loss, gateway metrics, and wireless signal quality.

For details, see:

* [Endpoint Agent Views](https://docs.thousandeyes.com/product-documentation/end-user-monitoring/viewing-data/agent-views)
* [Endpoint Agent Scheduled Tests View](https://docs.thousandeyes.com/product-documentation/end-user-monitoring/viewing-data/endpoint-agent-scheduled-tests-view)
* [Data Collected by Endpoint Agent](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/data-collected-by-endpoint-agent)

## Building Dashboards

Use dashboards to visualize health trends, isolate issues faster, and share operational visibility with other teams.

![Dashboard view with Cisco Secure Access health metrics](/files/qFtEl24dC3O4wgO6htkG)

You can build dashboards manually or start from a template. For dashboard setup guidance, see [Getting Started with Dashboards](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-dashboards).


# Getting Started with API Tests

## Prerequisites

This article assumes that you have previously read the following getting started documentation:

* [Getting Started with Account Setup](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-account-setup)
* [Getting Started with Cloud and Enterprise Agent Tests](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-cloud-and-enterprise-agent-tests)

## What is an API Test?

While some of the other ThousandEyes web layer test types can also perform basic API endpoint testing, they can’t test as deeply as the API test. An API test can look deeper within a single target domain and test various API calls, including passing values and parameters from one call to the next. It provides metrics specifically for measuring API performance and capabilities specifically for easier troubleshooting.

## API Test Use Cases

Here are some examples of how you can use the API test type:

* **IT operations:** Understand the state of key internal application APIs in order to pass along the scope and probable root cause of an issue to the team or vendor responsible for that particular feature.
* **Network:** Identify loss along the network path so that if there is an outage in a key API due to network issues, it’s easier to find the probable root cause.
* **Applications:** Understand the performance of all of the application APIs, in order to monitor application health

## Creating an API Test

### Basic Configuration

These instructions focus on the minimum required data for creating an API test. The first part is accessing test settings, as shown below.

First, open the test configuration page:

1. Navigate to **Network & App Synthetics > Test Settings**.
2. Click **+ Add New Test** and select **API** from the **Web** category.

Optionally, enter a test name and a description, and then continue to the basic test settings as shown below.

Next:

1. Click **Configure Target API** and enter at least one step in the Step Builder, as described in Part 2 below. The network target shown in the **Network Test Target** field is used for the network layer portion of this test (path visualization and network overview).
2. On the **Basic Configuration** tab, choose at least one Cloud or Enterprise Agent. If you choose one of your own Enterprise Agents, the Enterprise Agent must have BrowserBot installed.
3. Click **Run Once** to run an instant test.
4. Click **Create New Test** to save the test. The test will start running immediately.

After waiting a few test rounds, you can see test results in **Network & App Synthetics > Views**.

The API test type supports client certificate authentication, similar to all other web test types. For the API test type, this setting is found on the **Network & App Synthetics > Test Settings > Advanced Settings** tab. You can selectively disable this setting per API call in the **Authentication** tab of the Step Builder.

On the **Advanced Settings** tab, the **Specify Domain** is an input field that allows the use of wildcards (“\*”) to specify the domains to which the client certificate will be sent. For example `*.thousandeyes.com`. If this field is empty, the client certificate will be sent to *all* domains defined in the API step builder.

### Step Builder

These instructions focus on the minimum required data for creating an API test. The second part is adding a step using the Step Builder, as shown below. (Although the absolute minimum data entry required is a single step with an endpoint, realistically you’d configure a few more items for things like authentication or parameters as well.) For more information, see [Using the Step Builder](https://docs.thousandeyes.com/product-documentation/api-test/using-the-step-builder).

Continue in the Step Builder, under Step 1.

1. Enter a step name, for example “Status Check”.
2. Leave GET as the default selection on the dropdown.
3. Enter a **Request URL** of `https://api.thousandeyes.com/v7/status`. The first portion of the URL is the domain name of the Target API, which remains the same in all steps for this API test.
4. Click **Save Configuration** to return to the Test Settings configuration screen.

There’s one default assertion rule already in place for a generic “ok” status code 200, so you don’t need to add any for this basic exercise.

### Run an Instant Test and Save the Test Configuration

The last part before saving the test settings is to run an instant test to ensure that your API test is configured correctly. After completing the Step Builder, you’ll be back on the main test settings screen. From here, you’ll still need to complete the task of saving and enabling the API test.

Click **Run Once** at the bottom of the new test **Basic Configuration** tab.

* If all is well, you’ll see a test view window in a new browser tab, showing test results.
* If there’s a test configuration error that prevents the test from running at all, you’ll see a ThousandEyes error message.
* If the test was able to run but one of the values is wrong, for example the domain itself does not exist or the key-value pair was rejected or not recognized, there will be an error shown on the test view window itself.

At this point you can save the test by clicking the **Create New Test** button on the **Configuration** tab. The test will be enabled by default, which means it will run on the interval specified in the test settings. As the test runs, it will build up a history that you can see in the test view. If you don’t want to consume too many units, but you want to keep working on the test configuration later, you can also save the test configuration but deselect the Enable check box next to it on the Test Settings main screen.

## Interpreting Test Results

After creating an API test, you will want to look at the results. See [Reading the API Test Views](https://docs.thousandeyes.com/product-documentation/api-test/api-test-type-view) or, for more general information, [Getting Started with Views](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/viewing-data/getting-started-with-views).

## Additional Features

### Assertion Rules

Assertion rules determine what constitutes a minimally successful API test. When you configure a new API test, there’s a default rule already in place that specifies an HTTP status code of 200 (OK) which indicates that the HTTP request, in this case an API call, succeeded: the client requested something and the server provided it.

You can configure in the **Assertion Rules** tab of the Step Builder. See [Using the Step Builder](https://docs.thousandeyes.com/product-documentation/api-test/using-the-step-builder) for more information.

## Next Steps

For next steps, check out the following articles:

* [Getting Started with Dashboards](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-dashboards)
* [Getting Started with Views](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/viewing-data/getting-started-with-views)
* [Alerts](https://docs.thousandeyes.com/product-documentation/alerts)
* [Getting Started with Transactions](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-transactions)


# Getting Support from ThousandEyes

As a ThousandEyes user, you may encounter situations that require assistance from our Customer Engineering team, or additional support.

This guide aims to help you understand when and how to contact ThousandEyes Customer Engineering for assistance. Whether you need help with technical issues, product functionality, or troubleshooting, our dedicated support team is here to help 24 hours a day, 7 days a week. In addition, the Cisco AI Assistant can provide support with user troubleshooting and technical questions.

Below is an outline of the support we provide and the best ways to get in touch for quick and efficient assistance.

In this guide we will cover:

* [Cisco AI Assistant](#cisco-ai-assistant-integrated-in-thousandeyes)
* [Contacting Support](#contacting-support)
* [日本語対応について (Japanese-language support)](#日本語対応について-japanese-language-support)
* [Online collaboration](#online-collaboration)
* [Support team locations and supported languages](#support-team-locations-and-supported-languages)
* [Other useful links](#useful-links-and-articles)

## Cisco AI Assistant Integrated in ThousandEyes

{% hint style="warning" %}
Generative artificial intelligence-powered capabilities ("GenAI") are not available for ThousandEyes for Government.
{% endhint %}

The Cisco AI Assistant is integrated in ThousandEyes to provide users with enhanced troubleshooting support and situation analysis through AI-driven insights. You can find the AI Assistant in the top right of the ThousandEyes web application:

![Cisco AI Assistant Icon](/files/V4skXlBgxnjitkrhFEsn)

Once you've opened the assistant, navigated through the initial welcome pages (the first time only), and accepted the license agreement, a pop-out modal will appear on the right side of the web application.

![Cisco AI Assistant Modal](/files/zTcyWCFP2FHoCfEUf4zP)

From here, you can ask the assistant about network and app synthetics test data, troubleshooting questions, and general inquiries about the ThousandEyes product suite. The assistant will draw on various sources (including the product documentation), and provide those links at the bottom of the response.

Supported features for the AI assistant include:

**Troubleshooting Application Experience**

The assistant can help troubleshoot the performance and experience of specific applications by using events, alerts, and [Internet Insights](https://docs.thousandeyes.com/product-documentation/internet-insights) outage data (if purchased). It provides clear summaries of the issue type, start time, duration (if applicable), and the number of affected agents and tests in your account group. This will help you quickly pinpoint and better understand the root cause of performance issues, leading to faster resolution and reduced downtime.

You can ask the AI Assistant questions like:

* "Were there any alerts triggered for \[application name] today?"
* "How many agents are affected by the latest issue with \[application name]?"
* "What locations are experiencing problems with \[application name]?"

**Account Health Check**

The assistant can review the health and operational hygiene of your environment, and provide a prioritized summary of issues, with clear recommendations for updates and changes.

You can ask the AI Assistant questions like:

* "Are any of my enterprise agents offline or overloaded?"
* “Do any of my enterprise agents have errors?

**Documentation Analysis**

The assistant allows users to ask natural-language questions about the ThousandEyes product documentation and [API documentation](https://developer.cisco.com/docs/thousandeyes/), as well as [ThousandEyes public blogs](https://www.thousandeyes.com/blog/). It streamlines access to technical information, providing quick answers to product questions along with references and hyperlinks to supporting documentation for deeper exploration.

You can ask the AI Assistant questions like:

* "What are the supported metrics for Cloud Agent tests?"
* "How can I create a new test using the ThousandEyes API?"
* "What is the default interval for HTTP server tests?"

**Querying the API for Network and Application Synthetics Tests**

The AI Assistant can query for network and application synthetics tests.

You can ask the AI Assistant questions like:

* "What tests have I set up for Salesforce?"
* "Which locations am I monitoring Microsoft Teams from?"

### AI Data Privacy and Customer Security

At Cisco, we believe that generative artificial intelligence ("GenAI") can be leveraged to power an inclusive future for all. We also recognize that by applying this technology, we have a responsibility to mitigate potential harm. That is why Cisco adheres to our [Responsible AI Framework](https://www.cisco.com/c/dam/en_us/about/doing_business/trust-center/docs/cisco-responsible-artificial-intelligence-framework.pdf) (the "Framework"), which is based on [six principles](https://www.cisco.com/c/dam/en_us/about/doing_business/trust-center/docs/cisco-responsible-artificial-intelligence-principles.pdf) of Transparency, Fairness, Accountability, Privacy, Security and Reliability.

You can read more about Cisco ThousandEyes' approach to GenAI here: [Cisco ThousandEyes GenAI Transparency Technical Note](https://trustportal.cisco.com/c/r/ctp/trust-portal.html#/19769090650056326).

### Provide Feedback for the Cisco AI Assistant

You can provide feedback about the responses you get from the Cisco AI Assistant using the "thumbs up" or "thumbs down" and selecting the relevant checkboxes (Correct, Helpful, Other) underneath the response thread, and providing additional details regarding your experience.

![Cisco AI Assistant Feedback](/files/8kEoalXBZ8G3wlrrZQ7L)

We appreciate any feedback, as both positive and negative feedback helps us improve the experience.

{% hint style="warning" %}
ThousandEyes strongly recommends that you do not include any personal data, confidential information, or otherwise sensitive information in your feedback.
{% endhint %}

### Opting Out of the Cisco AI Assistant

The Cisco AI Assistant is enabled by default for all users. You can opt-out of all Cisco AI-based features available in ThousandEyes by navigating to **Manage -> Account Settings -> Organization Settings -> AI Features**, switching the toggle to **Off**, and clicking **Save Changes**.

{% hint style="warning" %}
Only organization administrators can configure this toggle.
{% endhint %}

## Contacting Support

The Customer Engineering team is here to help with the following types of inquiries:

* Technical questions
* Product functionality
* Configuration assistance
* Requests to analyze test results
* Reports of possible bugs or other platform issues
* Feature requests

{% hint style="info" %}
Customer Engineering cannot assist with sales-related questions or provide product demonstrations. For those inquiries please contact your personal customer success manager.
{% endhint %}

When contacting Customer Engineering, use the email address associated with your ThousandEyes account in order to ensure that you are associated with the correct organization and case history in the ticketing system.

Contact the ThousandEyes Customer Engineering team through these methods:

* [Email](#email): <support@thousandeyes.com>
* [Chat](#chat): **app.thousandeyes.com > Help & Support > Chat with Support**
* [Web](#web): **app.thousandeyes.com > Help & Support > Contact Support**
* [Telephone - Main](#phone): +1 919-993-2051
* [Telephone - ThousandEyes for Government customers](#phone): +1 877-669-1782

![Help & Support menu](/files/ExMgYo9rYQ6nKdsrHV3d)

### Email

For non-urgent inquiries or when you need to provide detailed information about your issue, you can send an email to our Support team at <support@thousandeyes.com>.

### Chat

For interactive support, the ThousandEyes app provides a chat client, which you can access from the Help and Support menu in the top bar of app.thousandeyes.com.

### Web

Customers who log into the ThousandEyes app have access to the [Support portal](https://success.thousandeyes.com/), where you can create a Support case, as well as view your Support case history and other Support information. You can also use this portal if your organization blocks live chat or email due to security requirements.

### Phone

For high-priority issues, you can contact ThousandEyes Customer Engineering at the numbers below. Callers are routed to the next available engineer.

* Global Support: +1 919-993-2051
* ThousandEyes for Government customers: +1 877-669-1782

## 日本語対応について (Japanese-Language Support)

日本国内のお客様を対象に、グローバルサポートチームのサブセットとして、日本語対応窓口を提供しています。Eメール <support@thousandeyes.com>、またはWebポータルまで、日本語でご連絡ください。

日本語対応ができるThousandEyesのサポートチームが、日本時間の月曜から金曜まで、9:00am - 5:00 pmにて受付（日本国民の祝日・Cisco年末年始休暇を除く）、翌営業日以内にご返信いたします。グローバルサポート同様、サポートケース番号が発行されます。なお、チャットによる日本語サポートは現在対応していません。

Translation of the above:

For customers in Japan, we provide a Japanese-language support desk as a subset of our global support team. Please contact us by email at <support@thousandeyes.com> or via our web portal. The ThousandEyes support team, who can speak Japanese, is available 9:00am - 5:00pm (Japan time), Monday through Friday (excluding Japan national holidays and Cisco's end-of-year shutdown period) and will respond within the next business day. Similar to global support, a support case number will be issued. Please note that Japanese-language support via chat is currently not available.

## Online Collaboration

During a support session, the team may request a screen-sharing session using Webex or your company’s screen-sharing solution.

To facilitate effective online collaboration, first [gather the necessary information](#information-we-need). Our supporting engineers require this information before joining a collaboration, in order to run checks and investigations on the ThousandEyes side of the issue.

### Information We Need

Before you contact Customer Engineering, collect the following information:

* Names of any agents involved.
* Names of any tests involved.
* Names (and, if possible, IDs) of any alerts involved.
* Logs or diagnostic files from the involved agents.
* A clear description of the issue:
  * Are you having issues installing an agent?
  * Is an agent not checking in?
  * Is a new test not worked as expected?
  * Is a test suddenly failing and you need to know why?
  * Do you need an alert explained?

{% hint style="info" %}
We recommend provide a screenshot with as wide a view as possible to ensure we have the required context for the issue.
{% endhint %}

The following additional information is also needed, if relevant to your specific issue:

* For **transaction tests** that are not working in the recorder:
  * Save the test to the portal so that we can work with you on it.
* For **API related questions**, include the following data to allow us to find the specific call in the logs:
  * The API URL.
  * The account group used for the API call, especially if the `?aid=###` parameter is used.
  * The user making the call.

When you provide this background information, we can help you more effectively.

### Sensitive Information to Avoid Sharing

Do not share sensitive information, such as passwords, API tokens, or files containing proprietary information.

These may include, but are not limited to:

* Passwords (ThousandEyes account, Web or Voice Layer Tests, private keys for digital certificates)
* API tokens
* Files containing sensitive information (screenshots, transaction test scripts, packet captures, configuration files

## Support Team Locations and Supported Languages

Customer Engineering team members are located in the United States, Mexico, Australia, India, Poland, and Japan.

By default, the support language is English, but it may be possible to converse with a Support person in a local language during business hours if requested. The exception is Japan, where communication in Japanese is available only via email, not chat. For customers who do not speak or write in English, a translator will be made available so they can communicate in their local language.

## Case Handling Priorities

To better enable the Cisco ThousandEyes Support team to meet both the [Cisco ThousandEyes Support Policy](https://www.thousandeyes.com/pdf/ThousandEyes_Support_Policy.pdf) and your individual needs, we have implemented a two-aspect priority system. Cases are assigned the approriate priority level based on the support policy, while also being assigned a customer priority level, based on your own assessment of the issue.

This enables you to help tell us which cases within a given ThousandEyes priority level are more urgent than others.

The priority system looks as follows:

* ThousandEyes Priority 1 (Urgent) \[Critical impact on your business operations]
  * Customer Priority Critical
  * Customer Priority Major
  * Customer Priority Medium
  * Customer Priority Minimum
* ThousandEyes Priority 2 (High) \[Substantial impact on your business operations]
  * Customer Priority Critical
  * Customer Priority Major
  * Customer Priority Medium
  * Customer Priority Minimum
* ThousandEyes Priority 3 (Medium) \[Minimal impact on your business operations]
  * Customer Priority Critical
  * Customer Priority Major
  * Customer Priority Medium
  * Customer Priority Minimum
* ThousandEyes Priority 4 (Low) \[No impact on your business operations]
  * Customer Priority Critical
  * Customer Priority Major
  * Customer Priority Medium
  * Customer Priority Minimum

## Useful Links and Articles

* [Requesting a ThousandEyes demo](https://www.thousandeyes.com/request-demo/)
* Webex
  * [ThousandEyes Webex](https://thousandeyes.webex.com): To join without installing software, use the **Join by browser** option. The Support team will provide the meeting information.
  * [Setting up and testing Webex](https://www.webex.com/test-meeting.html): Follow the directions to set up and test Webex on your computer. Perform the Webex test on the same network you will use during your meeting.
* [Sharing test data](https://docs.thousandeyes.com/product-documentation/tests/sharing-test-data#snapshots): When you submit a Support request about test results, the best way to provide us information is by sharing a snapshot link.
* [Troubleshooting Endpoint Agent issues](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/troubleshooting/troubleshooting-endpoint-agent-issues): Problems that cannot be solved solely by inspection of log files may require a remote desktop session with a Customer Engineer to investigate the agent and the system on which the agent runs.
* Connecting to Enterprise Agents via SSH:
  * [Windows](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/connecting-to-the-thousandeyes-virtual-appliance-using-ssh-windows)
  * [Linux and macOS hosts](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/connecting-to-the-thousandeyes-virtual-appliance-using-ssh-mac-linux)
* [How Alerts Work](https://docs.thousandeyes.com/product-documentation/alerts)

We hope this guide helps you get the assistance you need from the ThousandEyes Customer Engineering team. If you have additional questions, don’t hesitate to reach out using the [contact methods](#contacting-support) provided.


# Notification of Upgrades, Maintenance and Outages

ThousandEyes releases periodic software updates and performs occasional maintenance. While we endeavor to update the system unobtrusively, some changes require us to take offline all or part of the platform, Cloud Agents or other infrastructure. Additionally, unplanned outages can infrequently occur. Customers who wish to receive information on updates, maintenance that requires downtime or unplanned outages can selectively subscribe to emails and to our ThousandEyes Operations Twitter feed.

Updates to the product, which introduce new features and bug fixes, typically occur on alternate Tuesdays, starting at 6 PM, Pacific time, but may also occur at other times. We update our Changelog on the [documentation site](https://docs.thousandeyes.com), with valuable information about newly available features and bug fixes.

When planned maintenance downtime is scheduled, we post a notice on the ThousandEyes [status page](https://status.thousandeyes.com/), as well as in the bell notifications menu of the platform. You can access the bell notifications menu through the bell icon on the menu bar of the ThousandEyes app:

![Notification alert feature](/files/-M5xtGedGbHG5XHUUTEu)

During unplanned outages, we post a notice on the status page, as well as tweeting from our @ThousandEyesOps handle.

For more information about the kinds of updates available in the bell notifications menu, see [Glossary: Bell Notifications](https://docs.thousandeyes.com/product-documentation/getting-started/thousandeyes-glossary#bell-notification).

## Subscribing to Email Notifications

To receive information on new ThousandEyes platform features and upgrades, or on maintenance that requires platform downtime, you can subscribe to email notifications. Whenever new content is published, subscribers receive an email notification, sent to the email address that is used as the ThousandEyes login.

* Information about the most recent releases is available in the [Changelog](https://docs.thousandeyes.com/whats-new/changelog) section of this documentation site.
* Announcements about planned and unplanned maintenance are posted on the [ThousandEyes status page](https://status.thousandeyes.com/).

To subscribe to notifications about documentation changes:

1. Log into [ThousandEyes](https://app.thousandeyes.com/) using the email address where you wish to receive the email announcements. You cannot subscribe an email address that does not correspond to an account in the ThousandEyes platform.
2. Click the **Help & Support** icon in the top bar of the screen; then click **Contact Support**.
3. In the new screen that appears, click the **Profile** tab to display your **Profile Settings**.
4. In the **Product Content Subscriptions** section, select the categories of content you want notifications for.
5. Click the **Update Preferences** button to save your changes.

![Profile Settings screen showing options for email notifications](/files/kklgKT3CA49WVFSZM6G1)

### Distribution of Email to Multiple Recipients

Customers who want to distribute email notifications to multiple users can configure a forwarding rule within their email system, to resend a received email.

Alternatively, customers can create an account in ThousandEyes whose username is the email address associated with a distribution list within their email system. For example, **<netops-thousandeyes-notifications@example.com>**.

## Following the Twitter/X Feed

For information on unplanned outages, you can follow the ThousandEyes Operations' Twitter handle: **@ThousandEyesOps**. The Twitter feed provides information on unplanned events as well as scheduled maintenance. To subscribe to the Twitter handle, go to the [ThousandEyes Ops Twitter page](https://twitter.com/ThousandEyesOps), then click the **Follow** button:

![ThousandEyes Operations Twitter page](/files/-M5xtGefPgg1IfW27nRb)

Following a Twitter feed requires a Twitter account. To unfollow the feed, consult Twitter's [support documentation for unfollowing](https://support.twitter.com/articles/15355-unfollowing-people-on-twitter).

You can integrate a Twitter feed with messaging tools such as Slack, allowing the feed's tweets to be distributed to people automatically. Here is an example of an integration with the tool that distributes the feed's tweets:

<https://get.slack.help/hc/en-us/articles/205346227-Adding-Twitter-to-Slack>


# New User FAQ

This Frequently Asked Questions document is meant to help answer general questions about the ThousandEyes platform and how to access it. Most answers are linked to other articles within the ThousandEyes documentation. If this article answers one of your questions, we encourage you to peruse other questions here to further your introduction.

## What Is ThousandEyes?

* [ThousandEyes](https://www.thousandeyes.com/) is a SaaS platform that allows you to run various tests to a target using various agents. Tests track metrics that can be monitored using customizable alert rules. You can set up notifications for these alert rules using email or other forms of communication.
* The ThousandEyes platform monitors DNS resolution, browser response characteristics, detailed aspects of network pathing and connectivity, the status of network routing, and VoIP streaming connection quality.
* Information about these different aspects of a network are portrayed in test results constructed from data collected by custom servers referred to as ThousandEyes agents. The agents examine a test target using methods developed by ThousandEyes which can be run as one-time only statistics or sampled over multiple intervals specified in customizable test configurations.
* The data that these tests collect can be reported to a dashboard or in other forms to provide a comprehensive umbrella of intelligence about various areas of hybrid cloud and private networks. Network paths are represented in a path visualization that maps the route of your traffic. This map gives you detail analogous to a street view on a physical map and describes the characteristics of the nodes on each path.

## How Do I Use ThousandEyes?

* Create a ThousandEyes trial account starting here: <https://www.thousandeyes.com/signup>
* Once you are logged in, you can create tests, work with agents, and set up alerting or other reporting mechanisms.
* If your organization already has an account, contact your organization admin to add your user profile.
* To learn more, see the [ThousandEyes documentation](https://docs.thousandeyes.com/) or contact <support@thousandeyes.com>.

## How Do I Reset My Password?

In the event your login password needs to be reset, do the following:

1. Click the password-reset link on <http://app.thousandeyes.com/login>.
2. Select **Forget password?**.

   An email message is sent to the email address you used to log in to the platform. Its subject line is "Password Reset".

   In some instances, this email may go to your spam folder, so look for it there if it does not appear to be sent before contacting Support.

   You may request a password reset email once per 24-hour period. The links in these emails are valid for 48 hours.

## I Haven't Received the Password Reset Email

Before checking with <support@thousandeyes.com>, you may be able to find the password reset email in your spam folder. Look for an email with the subject header "Password Reset". For more assistance, contact ThousandEyes Support.

## I Forgot to Activate My Account, and the Link Has Expired

When you create your ThousandEyes account, the system sends you an activation link. The activation link is valid for 72 hours. If your activation link has expired, click the **Re-Send Activation Link** button in the expiration message.

## How Do I Delete My Trial Account?

To delete your account:

1. Log in to the ThousandEyes platform.
2. Navigate to [Manage > Account Settings > Usage and Billing > Usage](https://app.thousandeyes.com/account-settings/usage-billing/?section=usage).
3. Under the **Organization Deletion** section, click **Delete**.

## Can User Logins Be Restricted to Use SSO Only?

Account users with the proper permissions can require users to log in via single sign-on or the ThousandEyes login page. To explore these options, do the following:

1. Go to **Manage > Account Settings > Users and Roles > Roles**.
2. Filter the list of permissions by entering "login" in the search box.

For detailed information about role-based access control, see [Role-Based Access Control](https://docs.thousandeyes.com/product-documentation/user-management/rbac/role-based-access-control-explained).

## How Many Users Can I Create?

There is no limit on the number of unique users a customer can add to their account, either within an organization or within an account group.

## When I Log In, I See "Cannot Log In Interactively"

This message means that your user profile does not have permissions to log in interactively with email and password. You will need to log in from the ThousandEyes SSO login page at <https://app.thousandeyes.com/login/sso>.

You can also add the *Login via ThousandEyes login page* permission to your user to log in interactively.

## Why Can’t I Create a Test?

Certain users have permissions to use parts of the platforms. There are cases where users are given access to the platform to run a test prepared by an administrative-level user. To have your permissions and role reviewed, contact the administrator of your ThousandEyes account.

To learn more about roles and permissions in the ThousandEyes platform, see [Role-Based Access Control](https://docs.thousandeyes.com/product-documentation/user-management/rbac/role-based-access-control-explained).

## There Are Restrictions on Using Cloud Agents Outside My Network. How Do I Get a List of IP Addresses?

You may need the IP addresses of ThousandEyes agents in order to construct firewall rules or similar filters. The ThousandEyes API provides the IP addresses of both Cloud Agents assigned to your organization and Enterprise Agents assigned to your account group. To query the ThousandEyes API use wget, cURL, a programming language which supports using RESTful APIs, or through a RESTful API client, such as [Postman](https://www.getpostman.com/). For more information about the API:

* The ThousandEyes API site has examples that represent queries you might use with your own account token. For more details, see the [ThousandEyes API documentation](https://developer.cisco.com/docs/thousandeyes/v7/)
* You can also download and use our **te-iplist** CLI utility to do this on Linux, macOS, or Windows. For instructions, see [How to Obtain a List of ThousandEyes Cloud Agent IP Addresses](https://docs.thousandeyes.com/product-documentation/global-vantage-points/obtaining-a-list-of-thousandeyes-agent-ip-addresses-with-te-iplist).

## Where Can I Get an Account Group Token?

The account group token is used to establish a unique connection with your Enterprise Agent and any specific account groups that a specific account user has on the ThousandEyes platform. You can retrieve this token in one of two ways:

* **Account Settings**
  * Go to **Manage > Account Settings > Users and Roles**, open the **Account Groups** tab, select the account group, and click the eye icon to show the token.
  * To see the **Account Groups** tab, you must have either the *Organization Admin* role or a role with the *View all account groups settings* permission.
* **Agent Settings**
  * Go to **Network & App Synthetics > Agent Settings**, open the **Enterprise Agents** tab, click **Add New Enterprise Agent**, select **Appliance**, and click the eye icon to show the token.
  * To see the token, you must have a role with the *Edit agents in account group* permission.

## How Do I Create My Own Agent?

You can deploy your own agent on hosts that you control. Go to [Network & App Synthetics > Agent Settings](https://app.thousandeyes.com/network-app-synthetics/agent-settings/enterprise/?section=agents) and click **Add New Enterprise Agent**.

Each package type has its own corresponding installation steps, listed under an "Installation Guide" or listed as scripted commands. Three package type deployments that can get you started quickly are **Appliance**, **Linux Package** or **Docker**. The three links below describe each of these in detail:

* [How to Set Up an Agent Using a Virtual Appliance](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/enterprise-agent-deployment-using-thousandeyes-virtual-appliance-ova)
* [Set Up an Enterprise Agent with a Linux Package](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/linux-package-agent-installation)
* [How to Set Up an Enterprise Agent Using Docker](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/docker-based-agent-installation)

## How Do I Deploy an Enterprise Agent Behind a Firewall?

When you set up an Enterprise Agent behind a firewall, there is additional configuration that needs to be done. Firewall rules must be set up to allow the agents to transmit and receive data with the ThousandEyes platform. Agents communicate with the platform using specific ports, so these must be allowlisted on the firewall. For more information, see the following articles:

* [Learn what ports ThousandEyes agents use to communicate with the platform](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/firewall-configuration-for-enterprise-agents)
* [Enterprise Agent Port Forwarding](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/enterprise-agent-port-forwarding)
* [NAT Traversal for Agent-to-Agent Tests](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/nat-traversal-for-agent-to-agent-tests)

## How Do I Recover a Deleted Test?

To recover a deleted test:

1. Go to **Network & App Synthetics > Test Settings > Tests**.
2. Above the list of tests, next to the trash-can icon, click the link that lists the number of deleted tests.
3. In the **Deleted tests** dialog, click **Recover** for the test you want to restore.

## Why Can't I Change a Test's Target After I Create the Test?

The target of an existing test cannot be edited, in order to preserve the data that is collected for each distinct target. If a test target were editable, this would put two separate data sets into a single result. An older result for a different target would be placed alongside data that is intrinsically unrelated. Doing this would affect the integrity of any historical test results because the objects being tested don't match exactly. Different targets yield different results so they are kept separate with that intention in mind.

After a test is created, any part of the configuration can be edited except the test target.

To edit a test's target, you can instead duplicate it, edit the target of the duplicate, and save the duplicate.

For more information, see [Working with Test Settings](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests/working-with-test-settings).


# ThousandEyes Glossary

## A-B-C

### Account group

A ThousandEyes account group within an [organization](#organization) represents a business unit, subsidiary, or other defined customer group such as local branch or IT department.

See [What Is an Account Group?](https://docs.thousandeyes.com/product-documentation/user-management/account-groups/what-is-an-account-group) for more information.

### Active alert

An alert is considered active when an associated test has failed or experienced errors for a specified number of consecutive test rounds, per the associated [alert rule](#alert-rule).

See [Getting Started with Alerts](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-alerts) for more information.

### Activity log

The activity log provides a history of actions by the ThousandEyes users in your organization, including test creation, updates, deletions, login, logout, and other activities. The activity log also displays a timestamp and user metadata for each event.

See [Working With the Activity Log](https://docs.thousandeyes.com/product-documentation/user-management/user-activity/working-with-the-activity-log) for more information.

### Affected test

In [Internet Insights](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-internet-insights), an affected test is one of your ThousandEyes tests that is indirectly impacted, or could potentially be impacted, by an outage elsewhere in Internet Insights. A test can be affected even if that test is not showing any obvious errors or triggering alerts.

See [My Affected Tests](https://docs.thousandeyes.com/product-documentation/internet-insights/using-alerts-and-dashboards-with-internet-insights/my-affected-tests) for more information.

### Agent

Agent refers to ThousandEyes software packages (servers) installed at specific global locations, used by customers to run tests against specified domains or targets. Agents are also referred to as global vantage points. Enterprise Agents are installed and maintained by customers inside their own networks, while Cloud Agents are maintained by ThousandEyes and are available to all customers. Endpoint Agents run on end-user computers and thus don't necessarily have a fixed location.

See [Global Vantage Points](https://docs.thousandeyes.com/product-documentation/global-vantage-points) for more information.

### Agent cluster

Agent clusters are multiple ThousandEyes Cloud and Enterprise Agents operating together to run ThousandEyes tests from a single location. Clustering simplifies the agent selection process and facilitates load balancing for new tests.

You can manage clusters for your own Enterprise Agents. For more information, see [Working with Enterprise Agent Clusters](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/working-with-enterprise-agent-clusters).

### Alert

An alert in ThousandEyes is an on-screen notification that one or more of your ThousandEyes tests is currently exceeding a defined error threshold. You can also set up alerts for [WAN Insights](https://docs.thousandeyes.com/product-documentation/wan-insights) when certain key indicators are outside of specified thresholds. Alerts are assigned to tests through [alert rules](#alert-rule). ThousandEyes alerts can be sent to third-party systems using [notifications](#notification).

See [Getting Started with Alerts](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-alerts) and [Alerts](https://docs.thousandeyes.com/product-documentation/alerts) for more information.

### Alert rule

An alert rule is a condition or a set of conditions that you configure in order to highlight or be notified of events of interest in your ThousandEyes tests. When an alert rule’s conditions are met, the associated alert is triggered and the alert becomes [active](#active-alert). It remains active until the alert is cleared. Alert rules are reusable across multiple tests.

See [Getting Started with Alerts](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-alerts) for more information.

### Alert trigger

An alert trigger is the element that a specific test type is set to examine. Some of these elements are:

* For Cloud and Enterprise Agent tests, the alert is triggered by agents.
* For Endpoint Agent tests, the alert is triggered by visited sites or by Endpoint Agents.

See [Local Alert Conditions](https://docs.thousandeyes.com/product-documentation/alerts/creating-and-editing-alert-rules/global-and-location-alert-conditions#location-alert-conditions) for more information.

### Application

In [WAN Insights](https://docs.thousandeyes.com/product-documentation/wan-insights), an application (application category) is a pre-selected bundle of applications within WAN Insights, such as Voice or Google Workspace, that share similar characteristics.

See [Application Categories](https://docs.thousandeyes.com/product-documentation/wan-insights/how-it-works/application-categories) and [Adding Business-Critical Applications to WAN Insights](https://docs.thousandeyes.com/product-documentation/wan-insights/tasks/custom-application-categories) for more information.

### Bell Notification

In the ThousandEyes app, the status bar at the top of the page shows a bell icon. This menu provides a list of any informational notifications pertaining to your ThousandEyes account and application. You can clear these notifications by clicking the "x" button next to a single item in the list, or you can click "dismiss all".

Available integrations and test recommendations will also appear here. The bell notification area also alerts you if have any tests in a draft state.

* For more information about the bell notifications menu, see [Notification of Upgrades, Maintenance and Outages](https://docs.thousandeyes.com/product-documentation/getting-started/notification-of-upgrades-maintenance-and-outages)
* See the [Notifications](https://docs.thousandeyes.com/product-documentation/getting-started/thousandeyes-glossary#notifications) entry for other kinds of notifications.

### Built-in dashboard

Refers to ThousandEyes system-defined [dashboards](#dashboard). Built-in dashboards are not editable. However, you can copy a built-in dashboard and make changes to the copy.

See [Dashboards](https://docs.thousandeyes.com/product-documentation/dashboards) and [Getting Started with Dashboards](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-dashboards) for more information.

### Catalog

In [Internet Insights](https://docs.thousandeyes.com/product-documentation/internet-insights), the catalog is a database of internet service providers, categorized by provider name, provider type, and network identifier.

See [Configuring Internet Insights](https://docs.thousandeyes.com/product-documentation/internet-insights/int-config) for more information.

### Cleared alert

Cleared is a signal that an [alert](#alert) is no longer [active](#active-alert), meaning that the conditions triggering it are no longer in effect. You can also manually clear an alert, or the platform can auto-clear it if an agent fails to send data for 12 hours.

See [Getting Started with Alerts](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-alerts) for more information.

### Cloud Agent

A Cloud Agent is a ThousandEyes software agent that is available immediately to customers for running tests, with no administrative responsibilities. Cloud Agents provide globally distributed vantage points throughout the internet and are maintained by ThousandEyes.

See [Cloud Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/cloud-agents) for more information.

### Credentials repository

The credentials repository is used in ThousandEyes Browser Synthetics transaction tests to store and control access to login credentials, while keeping secure strings, such as passwords, hidden.

See [Working With Secure Credentials](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/getting-started/working-with-secure-credentials) for more information.

### Custom webhook

Custom webhooks in ThousandEyes are used to send notifications about ThousandEyes [alerts](#alert) to external systems.

See [Custom Webhooks](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-webhooks) for more information.

## D-E-F

### Dashboard

ThousandEyes dashboards show customized live views of your test data, as well as Internet Insights collective intelligence. For example, you can set up a dashboard based on Internet Insights that shows application outages related to your main SaaS provider, alongside internet outages that affect your users’ ability to access those domains.

See [Dashboards](https://docs.thousandeyes.com/product-documentation/dashboards) for more information.

### Device layer

ThousandEyes' device-layer monitoring uses Enterprise Agents to poll your network devices using the Simple Network Management Protocol (SNMP).

See [Device Layer](https://docs.thousandeyes.com/product-documentation/device-layer) section for more information.

### Dynamic test

With dynamic tests, you can evaluate a desktop application's performance without manually setting up an IP address or hostname. These tests function similarly to ThousandEyes agent-to-server scheduled tests, except that with dynamic tests, ThousandEyes selects the endpoints to monitor. Used with Endpoint Agents.

See [Dynamic Tests](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents#dynamic-tests) for more information.

### Embedded widget

An embedded widget is a ThousandEyes dashboard [widget](#widget) that is referenced in the HTML source code of an external web page to make information available to viewers outside of your ThousandEyes organization. The embedded widget provides the same information via the external web page without requiring a ThousandEyes login.

See [Embedding Dashboard Widgets in External Web Sites](https://docs.thousandeyes.com/product-documentation/dashboards/embedding-dashboard-widgets-in-external-web-sites) for more information.

### Enabled

Enabled applies to tests, agents, and alert rules.

* A ThousandEyes test that is enabled is actively running on one or more agents. Tests that are configured but not enabled do not consume units.
* An alert rule is enabled when it is applied to a particular test.
* A ThousandEyes agent is enabled when it is available for tests. If you disable an Enterprise Agent, you cannot run tests on it until you re-enable it.

See [Working with Test Settings](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests/working-with-test-settings) for more information.

### Endpoint Agent

The ThousandEyes Endpoint Agent is an application that is installed on end-user computers to measure network and application performance from the vantage point of a regular end user. Endpoint Agents can be deployed on- and off-premises to collect performance measurements from almost every possible user environment. Endpoint agents provide you with the ability to identify and diagnose end-user issues in near real-time.

See [Endpoint Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents) for more information.

### Endpoint pair

Within [WAN Insights](https://docs.thousandeyes.com/product-documentation/wan-insights), an endpoint pair refers to a connection between two routers located at different sites. From a data standpoint, WAN Insights endpoints are entities to which network traffic is routed, or which produce or consume traffic. Examples of endpoints include edge routers, SaaS data centers, and routing prefixes.

See [Sites, Routers, Paths, and Interfaces](https://docs.thousandeyes.com/product-documentation/wan-insights/how-it-works/sites-routers-paths-interfaces) for more information.

### Enterprise Agent

An Enterprise Agent is ThousandEyes software running on a Linux platform deployed and managed by a ThousandEyes customer for their exclusive use, to test targets from inside the customer's own network, or from within infrastructure under the customer's control. By contrast, ThousandEyes [Cloud Agents](#cloud-agent) are managed by ThousandEyes, shared by all customers, and are used for outside-in network testing.

See [Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents) for more information.

## G-H-I-J-K

### Impacted user

Within WAN Insights, an impacted user refers to the end user of a business application within an enterprise network, who may be impacted by poor network performance.

See [WAN Insights Introductory Tour, Part 1](https://docs.thousandeyes.com/product-documentation/wan-insights/wan-insights-quick-start/wan-insights-tour-part-1) for more information.

### Instant test

An instant test runs a single measurement using the **Instant Test** control. Use it to validate a test configuration - either when you first configure a new ThousandEyes Cloud or Enterprise Agent test, or from an existing test view. Instant tests consume [units](#unit-unit-consumption), and thus they count towards monthly unit consumption.

See [Working with Instant Tests](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests/working-with-instant-tests) for more information.

### Integration

ThousandEyes integrations allow you to use the ThousandEyes platform with other tools, to make the best use of ThousandEyes data for your organization. A common integration is to collect ThousandEyes [alert](#alert) notifications and display them in other communication systems such as Slack or PagerDuty.

* See [Custom-Built Integrations](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-built-integrations) for ways to integrate ThousandEyes with other products; for example, displaying ThousandEyes test data in AppDynamics.

### Internet Insights

ThousandEyes Internet Insights uses the collective intelligence of ThousandEyes’ entire agent network to show outages that may affect you, even if you’re not directly testing against those targets yourself. If enough ThousandEyes agents testing towards the same target report problems, ThousandEyes makes the inference that the cluster of errors represents a real outage and displays it on the **Internet Insights > Outages** map.

For a more complete list of terms related to Internet Insights, see the Internet Insights [Terminology](https://docs.thousandeyes.com/product-documentation/internet-insights/int-terminology) page.

### Interval

A test interval is the frequency at which a test is run. For example, every two minutes or every hour. Intervals are configured as part of each test’s settings.

See [Working with Test Settings](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests/working-with-test-settings) for more information.

## L-M-N-O

### Labels (deprecated)

Labels were a legacy way to organize and filter tests, agents, endpoint agents, and dashboard groupings. Labels have been upgraded to [Tags](#tags). All existing labels were automatically migrated to the new tagging system. See [Tags](#tags).

### Monitored domain set

A monitored domain set consists of domains that you want end-user performance monitoring information about. The best practice is to use business-relevant domains for tools and sites that your end users access. Used in **Endpoint Agents > Browser Session Settings**.

See [Configure Browser Sessions](https://docs.thousandeyes.com/product-documentation/end-user-monitoring/browser-session/configure-browser-session) for more information.

### Metrics

In a ThousandEyes test [view](#view), metrics are different measures that can be selected using a drop-down filter list. For example, a page load test might have page load time as one of the available metrics.

See [Getting Started with Views](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/viewing-data/getting-started-with-views) for more information.

### Notification

A notification generally refers to a message sent automatically upon certain events to your email, PagerDuty, Slack, AppDynamics, ServiceNow, or other tool configured through a [custom webhook](#custom-webhook). Notifications apply to [alerts](#alert), WAN Insights [recommendations](#recommendation), usage limit notifications, and to ThousandEyes documentation updates.

For more information:

* See [Integrations](https://docs.thousandeyes.com/product-documentation/integration-guides) for ways to send automatic notifications from ThousandEyes alerts to third-party systems, including both custom webhooks and pre-configured third-party integrations.
* See [Email Notifications](https://docs.thousandeyes.com/product-documentation/wan-insights/tasks/email-notifications) for information about notifications for WAN Insights recommendations.
* See the entry [Bell Notifications](https://docs.thousandeyes.com/product-documentation/getting-started/thousandeyes-glossary#bell-notifications) for information about the notifications that appear on the status bar when you are logged into the ThousandEyes app.

### Organization

An organization within ThousandEyes represents the overall billable entity.

See [Role-Based Access Control](https://docs.thousandeyes.com/product-documentation/user-management/rbac/role-based-access-control-explained) for more information.

### Outage

Outages within Internet Insights refer to global events that impact a large number of servers or Autonomous Systems (AS).

* An application outage is an event for which some or all servers that belong to the same application are failing at the same point in time.
* A network outage is an event with 100% packet loss in the same Autonomous System (AS) and the same metropolitan location during the same period of time.

See [Internet Insights](https://docs.thousandeyes.com/product-documentation/internet-insights) for more information.

### Overage

An overage is the result of exceeding your monthly unit allowance. Overages can be enabled or disabled for a particular customer. Customers with overages disabled are prevented from using more units than their monthly allowance. For those customers who have overages enabled, the overage may or may not be billed at the end of the month, depending on the customer's plan.

See [Overages](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/about-usage-units#overages) for more information.

## P-Q-R

### Path Quality

The WAN Insights Path Quality metric aggregates network performance measures (loss, latency, and jitter), and expresses the result as a single weighted percentage. This percentage expresses the likelihood of violating a defined quality threshold in the near future, which is a risk to be mitigated.

See [Understanding Quality](https://docs.thousandeyes.com/product-documentation/wan-insights/how-it-works/understanding-quality) for more information.

### Package

In [Internet Insights](https://docs.thousandeyes.com/product-documentation/internet-insights), a package is a collection of Internet Insights providers with the same type and region, for example North America ISPs. Customers license a package in order to display outages originating from the providers included in the package.

See [Configuring Internet Insights](https://docs.thousandeyes.com/product-documentation/internet-insights/int-config) for more information.

### Package license

For Internet Insights, a package license allows you to select a group of global providers to monitor. You can purchase multiple licenses and re-assign them as needed.

See [Configuring Internet Insights](https://docs.thousandeyes.com/product-documentation/internet-insights/int-config) for more information.

### Private snapshot

A private snapshot is a way to permanently save a time segment of test data for your own account group. Similar to a [snapshot](#snapshot), a private snapshot is specific to a particular test, is private to your account group, and does not expire. Private snapshots were formerly referred to as *saved events*.

See [Retaining Data Beyond the 90-Day Limit](https://docs.thousandeyes.com/product-documentation/user-management/user-activity/retaining-data-beyond-the-90-day-limit) for more information.

### Provider type

Within Internet Insights, a provider type refers to the primary service focus of various global connectivity providers, for example SaaS or ISP. For providers that might offer more than one type of service, the provider type is determined in part by the type of data that ThousandEyes is able to collect through various types of testing.

See [Configuring Internet Insights](https://docs.thousandeyes.com/product-documentation/internet-insights/int-config) for more information.

### Quality of Experience

The Quality of Experience (QoE) score in WAN Insights is a calculated score based on aggregated Quality of Service (QoS) measurements for loss, latency, and jitter. Note that the QoE score indicates a level of risk, not an actual network outage.

See [Understanding Quality](https://docs.thousandeyes.com/product-documentation/wan-insights/how-it-works/understanding-quality) for more information.

### Quality of Service

Quality of Service (QoS) in WAN Insights measures network performance at the circuit level, between endpoint pairs. Quality of service is measured separately for loss, latency, and jitter, as a weighted percentage that expresses how close each performance measure is to its threshold.

See [Understanding Quality](https://docs.thousandeyes.com/product-documentation/wan-insights/how-it-works/understanding-quality) for more information.

### Quota

Quotas are used to ensure that [unit](#unit-unit-consumption) consumption, either at the [organization](#organization) or the [account group](#account-group) level, does not exceed a defined monthly cap or threshold. If the quota is exceeded, you will not be able to set up new scheduled tests, and/or some scheduled tests may be automatically disabled to stop unit consumption.

See [Setting Quotas](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/setting-quotas) for more information.

### Real User Test

The real user test is an Endpoint Agent feature to track a website's performance that is included within a monitored domain set. A real user test records both in-browser and network performance metrics.

See [Real User Tests](https://docs.thousandeyes.com/product-documentation/end-user-monitoring/browser-session) for more information.

### Recommendation

#### Context: Test Recommendations

For some integrations with third-party products, the ThousandEyes platform can offer *recommended tests*. Once you have set up the integration, ThousandEyes can suggest useful tests for monitoring the services you rely on.

For more information, see

* [Test recommendations with AWS API Gateway](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-built-integrations/aws-for-test-recs)
* [Test recommendations with AppDynamics](https://docs.thousandeyes.com/product-documentation/integration-guides/custom-built-integrations/appdynamics-for-test-recs)

#### Context: WAN Insights

A recommendation from WAN Insights refers to making network path or traffic routing changes at a particular network site in order to improve performance for a particular application category.

See [Understanding Recommendations](https://docs.thousandeyes.com/product-documentation/wan-insights/how-it-works/understanding-recommendations) for more information.

### Recorder

The ThousandEyes Recorder provides an integrated development environment (IDE) for creating, validating, and enhancing transaction test scripts based on your browser actions.

See [ThousandEyes Recorder](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/getting-started/thousandeyes-recorder) for more information.

### Role

Users are assigned to roles, which have a set of permissions applied. The permissions determine how much functionality the user can partake of on the ThousandEyes platform. ThousandEyes has three default roles, though customers can create customized roles within their organization, too.

See [Role-Based Access Control](https://docs.thousandeyes.com/product-documentation/user-management/rbac) for more information.

## S-T

### Shared by ThousandEyes

*Shared by ThousandEyes* refers to built-in test configurations provided by ThousandEyes. You can choose to activate or enable these tests for your own use.

For more information, see [Shared by ThousandEyes](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-cloud-and-enterprise-agent-tests#shared-by-thousandeyes).

### Snapshot

Snapshots apply to [dashboards](#dashboard) and also to test data.

### Tags

Tags are key-value pairs used to organize and filter tests, agents, endpoint agents, dashboards, and Internet Insights providers. You can apply tags to group related resources and use tag selectors in filters, alert rules, and dashboards. Tags replace the legacy [Labels (deprecated)](#labels-deprecated) feature. Manage tags from **Manage > Tags**.

See [Working with Dashboard Tags](https://docs.thousandeyes.com/product-documentation/dashboards/dashboard-labels) and [Working with Agent Settings](https://docs.thousandeyes.com/product-documentation/global-vantage-points/working-with-agent-settings) for more information.

* Dashboard snapshots represent a specific time range of the dashboard’s data. Snapshots can be created on demand, or created automatically according to a schedule and emailed to a list of recipients. See [Dashboard Sharing and Snapshots](https://docs.thousandeyes.com/product-documentation/dashboards/dashboard-shares-snapshots) for more information.
* For test data, the snapshot feature allows you to provide a URL to a read-only ThousandEyes test results web page at a specified point in time, viewable by anyone who has the link. See [Sharing Test Data](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests/sharing-test-data) for more information.
* A private snapshot (formerly called a saved event) is visible only within your account group.

### Template

A template is a suite of ThousandEyes resources designed for monitoring a target, based on the best practices for that particular type of target.

See [Templates](https://docs.thousandeyes.com/product-documentation/tests/templates) for more information.

### Test

A ThousandEyes test is a synthetic network probe with a user-specified target that runs at regular intervals from a ThousandEyes software agent. Tests are user-configurable and consume [units](#unit-unit-consumption).

* See [Tests](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests) for information on scheduled tests run from Cloud or Enterprise Agents.
* See [Automated Session Tests](https://docs.thousandeyes.com/product-documentation/end-user-monitoring/automated-session-test) and [Scheduled Tests](https://docs.thousandeyes.com/product-documentation/end-user-monitoring/scheduled-tests) for information on tests run from Endpoint Agents.

### Test layer

A ThousandEyes test layer refers to layers of operation, but is not the same as the OSI 7-layer network model or the TCP/IP 4-layer model. The ThousandEyes test layers are Routing, Network, DNS, Web, and Voice. Test data over time is displayed in test [views](#view). Multiple test layers may be available within a single test view.

See [Tests](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests) for more information.

### Test round

A test round refers to a single measurement performed by a ThousandEyes scheduled test, as executed by one or more ThousandEyes agents, for a single point in time. For example, for a test running at 5-minute intervals, a single test round might show test results for 12:00 midnight UTC, while the next round would show results for 12:05 am UTC.

See [Working with Instant Tests](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests/working-with-instant-tests) for more information.

### Timeout

A test timeout specifies how long to wait before assuming that the test target is unresponsive.

See [Working with Test Settings](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests/working-with-test-settings) and [Test Type Layers and Units](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/test-layers-units) for more information.

### Transaction test script

A transaction test script is used in ThousandEyes Browser Synthetics transaction tests that simulate a multi-step user journey through a web site, for example online shopping.

For more information, first review the [ThousandEyes Recorder](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/getting-started/thousandeyes-recorder) page, and then review the entire section under [Transaction Test Developer Guide](https://docs.thousandeyes.com/product-documentation/browser-synthetics/transaction-tests/development-guide).

## U-V-W-X-Y-Z

### Unit, unit consumption

Units are the measure by which tests run on Cloud or Enterprise Agents are charged. Throughout the month, configured tests consume units against the customer's monthly unit allowance, which in turn impacts customer billing. Generally, customers cannot consume more units than their plan allows. Each test consumes a certain number of units based on the test type, interval, timeout, and the number and type of ThousandEyes agents running the test.

* See [About Units](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/about-usage-units) and [Calculating Units](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/calculating-units) for more information.
* See [Usage-Based Billing](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing) and [FAQs: Usage](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/usage-faqs) for more information.

### User

A ThousandEyes user is someone registered to use the ThousandEyes user interface and/or the API.

See [Role-Based Access Control](https://docs.thousandeyes.com/product-documentation/user-management/rbac) for more information.

### View

A ThousandEyes view refers to test data shown on a timeline. Every test in ThousandEyes has a **Views** screen, and each view has multiple view layers that represent different levels of networking, from the underlay all the way through HTTP and voice layers. There are views available under **Cloud & Enterprise Agents**, **Endpoint Agents**, **Devices**, and **Internet Insights**.

For information on the various view types, see:

* [Getting Started with Views](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/viewing-data/getting-started-with-views)
* [Single Agent View](https://docs.thousandeyes.com/product-documentation/end-user-monitoring/viewing-data/single-agent-view)
* [Multi-Service Views](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests/multi-service-views)
* [Internet Insights Views Screen](https://docs.thousandeyes.com/product-documentation/internet-insights/int-screens/int-views)

### WAN Insights

ThousandEyes WAN Insights is a predictive network optimization tool that uses a statistical model to examine historical data from your Cisco SD-WAN, in order to find the best paths for application traffic.

For a more complete list of terms related to WAN Insights, see the [WAN Insights Terminology and Reference](https://docs.thousandeyes.com/product-documentation/wan-insights/wan-insights-terminology) page.

### Widget

Widgets are customizable visual data displays on ThousandEyes [dashboards](#dashboard). Widget types include tables, bar and pie charts, time series, color grids, and maps. You can [embed](#embedded-widget) them on other web pages as well.

See [Dashboard Widgets](https://docs.thousandeyes.com/product-documentation/dashboards/dashboard-widgets) and [Embedding Dashboard Widgets in External Web Sites](https://docs.thousandeyes.com/product-documentation/dashboards/embedding-dashboard-widgets-in-external-web-sites) for more information.


# Global Vantage Points

ThousandEyes' global vantage points are lightweight, Linux-based software agents that allow users to run a variety of layered monitoring tests, in order to gain insight into network and application performance and user experience.

## Comparison of Agent Types

ThousandEyes provides three types of agent. Each type of vantage point provides similar capabilities, but serves different purposes, and exists in different environments:

* [Cloud Agents](#cloud-agents)
* [Enterprise Agents](#enterprise-agents)
* [Endpoint Agents](#endpoint-agents)

### Cloud Agents

Cloud Agents are installed and maintained by ThousandEyes, and are available immediately to customers to configure tests, with no administrative responsibilities. Cloud Agents are located in many cities and countries; see [this map](https://www.thousandeyes.com/product/cloud-agents) for the current list of locations. These agents provide "outside-in" visibility to web-based apps or API endpoints.

Cloud Agents provide most of the configuration options that Enterprise Agents provide, but because Cloud Agents are used by multiple customers, some features are not available. For example, Cloud Agents cannot be configured to run web-layer tests through a proxy server, as this would require all tests run by the agent to use the proxy. For use cases such as testing a cloud-based proxy server, customers must use Enterprise Agent or Endpoint Agent.

For more information, see [Cloud Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/cloud-agents).

### Enterprise Agents

Enterprise Agents are deployed by customers within their own infrastructure.

An Enterprise Agent can run every ThousandEyes test type (except Network Layer BGP tests, which are not run by agents). Additionally, Enterprise Agents can be either a source or target of an agent-to-agent test, which provides bi-directional network data (end-to-end metrics and the Path Visualization view) between itself and another ThousandEyes agent (Cloud or Enterprise).

Enterprise Agents are intended to be installed in server-type environments, and be online continuously in order to run scheduled tests. Enterprise Agents require systems administrators to provide resources such as time synchronization and firewall/packet filter rules for test and administrative traffic.

An Enterprise Agent can be installed in a virtualized environment (virtual machine or container) as well as installed directly on native Linux systems, and on certain types of hardware, such as Intel NUC or Cisco ISR and ASR routers. Installing the Linux package on a supported Linux distribution with administrative (root) access will provide extensive flexibility. Customers can combine Enterprise Agent functionality with other capabilities of the host, such as advanced routing and proxying, PKI/certificate functionality or other authentication, authorization and access control (AAA) technologies.

For more information, see [Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents).

### Endpoint Agents

Endpoint Agents are installed on a PC or Mac, and provide on-demand and real-time visibility into each employee’s experience of SaaS and internally-hosted apps, as well as underlying wireless LAN, WAN, Internet connectivity and system health.

For tests, Endpoint Agents have the most specialized purpose: to collect Web-layer “waterfall” data (i.e., HTTP archive format) and Network-layer data (including layer 2 information such as WiFi data) from workstation environments (although Windows Server installations are supported). Data collection is often performed on-demand, activated when a user experiences performance or other problems with web-based applications.

Endpoint Agents are quickly and easily deployed as browser plug-ins for Chrome or Internet Explorer, and can monitor any application that Chrome and Internet Explorer can access.

For more information, see [Endpoint Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents).


# Cloud Agents

Cloud Agents provide globally distributed vantage points throughout the Internet and are maintained by ThousandEyes.

They are located in over 200 cities and are connected to Tier 1, 2 and 3 ISPs, broadband service providers, and regional data centers of major cloud providers. For the current list of locations, see [this map](https://www.thousandeyes.com/product/cloud-agents).

{% hint style="warning" %}
ThousandEyes for Government users and environments have access to a separate list of Cloud Agents. For more information, see [ThousandEyes for Government](https://docs.thousandeyes.com/product-documentation/thousandeyes-for-government).
{% endhint %}

{% hint style="warning" %}
Customers may deploy tests for Cloud Agents under a ThousandEyes for Government subscription, but any such deployment would be outside of ThousandEyes’ FedRAMP®-authorized boundary. ThousandEyes' obligations under the Authorization to Operate and the FedRAMP baseline requirements would not apply to the Cloud Agents or the data transmitted to or from the Cloud Agents. Customers are solely responsible for accessing and utilizing the Cloud Agent in accordance with their security policies and applicable FedRAMP and federal compliance requirements.
{% endhint %}

A Cloud Agent is a server that is available immediately to customers for tests, with no administrative responsibilities. Any test type in the ThousandEyes platform can be run on a Cloud Agent. Cloud Agents are available for the use of ThousandEyes customers on a unit-consumption basis, and are shared by all customers.

## Cloud Agent Availability and Test Configuration

ThousandEyes reserves the right to modify or decommission Cloud Agent locations at its sole discretion. If a Cloud Agent is decommissioned, the following actions will occur:

* **Test Configuration**: The decommissioned agent will be automatically removed from any test configurations that include it.
* **Test Status**: Any tests that rely exclusively on a decommissioned Cloud Agent will be automatically disabled.

We recommend that you periodically review your test configurations to ensure they continue to meet your monitoring requirements and to verify that your tests remain active.&#x20;

## Limitations

Cloud Agents provide most of the configuration options that Enterprise Agents provide, but because Cloud Agents are used by multiple customers, some features are not available. For example, Cloud Agents cannot be configured to run Web Layer tests through a proxy server, as this would require all tests run by the agent to use the proxy. For use cases such as testing a cloud-based proxy server, use an Enterprise Agent or Endpoint Agent.

## Autonomous System (AS) Metadata

This product includes autonomous system (AS) names and related metadata from datasets maintained by internet registries and other publicly available resources. For a complete list of the source data sets used in this product, reference [Autonomous System (AS) Data Sources](https://docs.thousandeyes.com/product-documentation/tests/bgp-tests#autonomous-system-as-data-sources).


# Where Are Cloud Agents Available?

ThousandEyes provides cloud agents in [locations throughout the world](https://www.thousandeyes.com/product/cloud-agents), on multiple provider networks, for instant use by customers. The interactive map shows all current cloud agent locations. The map is updated as ThousandEyes adds more cloud agent locations.

You can make a request for a new cloud agent location through your ThousandEyes Account Manager, or [send the request](mailto:support@thousandeyes.com?subject=request+for+new+Cloud+Agent+location) to the Customer Engineering team.

{% hint style="warning" %}
ThousandEyes for Government users and environments have access to a separate list of Cloud Agents. For more information, see [ThousandEyes for Government](https://docs.thousandeyes.com/product-documentation/thousandeyes-for-government).
{% endhint %}

{% hint style="warning" %}
Customers may deploy tests for Cloud Agents under a ThousandEyes for Government subscription, but any such deployment would be outside of ThousandEyes’ FedRAMP®-authorized boundary. ThousandEyes' obligations under the Authorization to Operate and the FedRAMP baseline requirements would not apply to the Cloud Agents or the data transmitted to or from the Cloud Agents. Customers are solely responsible for accessing and utilizing the Cloud Agent in accordance with their security policies and applicable FedRAMP and federal compliance requirements.
{% endhint %}


# Webex Cloud Agents

ThousandEyes has Webex-specific Cloud Agents deployed at the front door of several Webex data centers responsible for serving customer traffic. These agents are available for general use by all ThousandEyes customers and are a tool to better monitor and troubleshoot your Webex performance. For more information about the key value of these agents, see [the Webex Monitoring solution page](https://www.thousandeyes.com/solutions/webex-monitoring).

Cloud Agents that are Webex-specific display the Webex icon, and are identified as such in parentheses after the location name, as shown below:

![](/files/1HLI7LCYP95iJxf7PNE6)

## Key Differences

There are a few key differences between these Webex Cloud Agents and our general Cloud Agents you see on the ThousandEyes platform:

* Most importantly, these agents can only be used as *test targets* and cannot be the source of any tests. This means that these agents **can only be used in agent-to-agent and RTP stream tests, and only as the target of that test**.
* These agents can perform bidirectional testing, but only after they are selected as a target for the test.
* You can use the Webex Cloud Agents only with other IPv4 agents. IPv6 testing is not supported with the Webex Cloud Agents.

{% hint style="info" %}
For tips on setting up tests to Webex Cloud Agents, see [Best Practices for Monitoring Webex with Cloud and Enterprise Agents](https://docs.thousandeyes.com/solution-guides/monitoring-applications-and-services/monitoring-webex-meeting-with-cea).
{% endhint %}

## Webex Cloud Agent Locations

For current Webex Cloud Agent locations, see [Webex Agents](https://www.thousandeyes.com/product/cloud-agents#webex-agents).


# AWS Wavelength Cloud Agents

AWS Wavelength is an infrastructure service that embeds AWS compute and storage capabilities within the 5G networks of communication service providers (CSP).

ThousandEyes has Cloud Agents within different AWS Wavelength-supported carriers, to allow you to simulate the performance of users accessing those applications via a 5G network.

These embedded deployments, known as Wavelength Zones, are optimized for mobile edge computing applications. They enable application traffic from 5G devices to reach application servers without leaving the telecom network, avoiding latency from multiple internet hops and maximizing the benefits of 5G's speed and bandwidth.

Monitoring the performance of these agents, deployed in a similar manner on a carrier's network, is crucial for accurate assessments of application and user experience. To facilitate this, ThousandEyes has Cloud Agents within various AWS Wavelength-supported carriers. This allows for the simulation of user performance when accessing applications via a 5G network.

## Use Cases

Two example use cases where you might leverage the agents are as follows:

* Case 1: A mobile gaming company provides servers in Verizon's Multi-Access Edge Computing (MEC) environment in order to provide the best performance to their mobile gamers. That MEC deployment relies on backend services and databases that run in a cloud provider or hybrid environment on the Internet. The ThousandEyes AWS Wavelength agent gives visibility between the MEC and the internet, allowing you to monitor the network quality of backend services.
* Case 2: A web application provider has its services running in a cloud provider, hybrid environment, or bare metal. Many of their customers use the mobile app or the browser on their mobile phones. The ThousandEyes AWS Wavelength agent will give them visibility into their mobile customers' quality of service from their carrier's MEC to the web application.

## Limitations

The main limitation for AWS Wavelength Cloud Agents is that they can only be used for agent-to-server tests, as they are behind some restrictions in the MEC, detailed in the [AWS documentation](https://docs.aws.amazon.com/wavelength/latest/developerguide/wavelength-quotas.html).

## Locations

For a complete list of AWS Wavelength Cloud Agent locations, see [Cloud Agents](https://www.thousandeyes.com/product/cloud-agents).


# Enterprise Agents

ThousandEyes Enterprise Agents are Linux-based software agents that you deploy and manage within your own network infrastructure, providing dedicated monitoring capabilities that are not shared with other customers, unlike ThousandEyes Cloud Agents. Enterprise Agents require only modest hardware resources and can be deployed across a variety of environments, including data centers, branch offices, and IaaS platforms, as virtual machines, Linux packages, Docker containers, or ISO images on supported hardware. Using active and passive monitoring, Enterprise Agents provide visibility into application performance, network paths, and dependencies from within your own environment.

## Deployment Types

Enterprise Agents can be installed in several different ways depending on your existing infrastructure and technical preferences.

### Linux Package

The Linux package is installed directly onto a compatible Linux operating system, such as Ubuntu or Red Hat. This method is ideal if you already have Linux servers running in your environment and want to add the agent software to them. Once installed, the agent runs quietly as a standard background service. This is a great choice if you prefer to control the security and compliance policy of the host running the agent.

### Docker Container

The Docker image is a lightweight, pre-configured container that runs on any Linux host with Docker installed. This deployment type is great for modern, containerized environments because it is quick to download, easy to start, and isolates the agent software from the rest of the host system.

{% hint style="info" %}
Docker running on Windows and Mac is not currently supported.
{% endhint %}

### Virtual Appliance

The ThousandEyes Virtual Appliance (TEVA) is a ready-to-use virtual machine that includes both the operating system and the agent software. You can deploy a TEVA agent into hypervisor environments like VMware ESXi, Oracle VirtualBox, or Microsoft Hyper-V. This is a great choice if you want a plug-and-play solution with a built-in web management console for easy configuration.

### Physical Appliance

The ThousandEyes Physical Appliance (TEPA) is a dedicated hardware solution where the operating system and agent are installed directly onto small factor devices like an Intel NUC or a Raspberry Pi. TEPA agents are ideal for locations where you need a physical device, providing the edge visibility into a branch office or remote site.

### Cisco Devices

Enterprise Agents can be installed on a range of supported Cisco devices, using Cisco Application Hosting, Catalyst Center, the SD-WAN Manager, MX Platform, and the Enterprise NFV Infrastructure Software (NFVIS). This allows you to gain network visibility without needing to purchase or manage additional servers or hardware.

## Common System Requirements

The following table outlines the key hardware requirements common to all Enterprise Agents, both with and without the BrowserBot module included.

{% hint style="info" %}
The BrowserBot module performs page load and transaction tests.
{% endhint %}

| Requirement         | With BrowserBot | Without BrowserBot |
| ------------------- | --------------- | ------------------ |
| CPU count           | 2               | 2                  |
| RAM                 | 2 GB            | 1 GB               |
| Hard disk space     | 20 GB           | 20 GB              |
| Network interface   | Required        | Required           |
| Internet connection | Required        | Required           |

For deployment-specific requirements, refer to the relevant installation documentation.

## Supported Operating Systems

ThousandEyes supports installing the Enterprise Agent on the following x64 (64-bit) operating systems:

* AlmaLinux 8 and 9
* Amazon Linux 2 and 2023
* Oracle Linux 8 and 9
* Red Hat Enterprise Linux 8 and 9
* Rocky Linux 9
* Ubuntu 22.04 and 24.04

{% hint style="info" %}
Access to the appropriate package repositories (APT, YUM, or APK, depending on the operating system) is required.
{% endhint %}

{% hint style="warning" %}
BrowserBot only works on Ubuntu if run inside a Docker container, due to operating system and Linux kernel dependencies. Amazon Linux 2 does not support BrowserBot.
{% endhint %}

{% hint style="warning" %}
While ThousandEyes Docker-based Enterprise Agents and Cisco devices using Cisco Application Hosting are built on Alpine Linux, ThousandEyes does not support the native installation of Enterprise Agents on Alpine Linux.
{% endhint %}

{% hint style="warning" %}
There is currently no native version of the Enterprise Agent software for Microsoft Windows or macOS. If you use these operating systems, you must use a virtualization product to host a ThousandEyes Virtual Appliance (TEVA).
{% endhint %}

## Next Steps

To install an Enterprise Agent, see [Enterprise Agent Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing). You will need to review the prerequisites and ensure your environment is configured correctly before choosing your deployment method.


# Data Collected by Enterprise Agents

This article explains the information captured by ThousandEyes Enterprise Agents, and information forwarded to ThousandEyes.

A Enterprise Agent is a system configured to run a supported version of Linux, which is deployed behind the firewalls of an organization in order to measure performance against either internal or Internet-based network assets. Enterprise Agents are typically deployed using virtualization, and can be installed either as a package, in a supported version of Ubuntu, Red Hat Enterprise Linux, or CentOS, or as a prepackaged virtual appliance, which can be simply deployed into a number of different hypervisor platforms.

The diagram below shows a simple version of the connectivity between a Enterprise Agent, network assets you are monitoring, and ThousandEyes.

![](/files/-M5xtPXCKe5GaYlufLmO)

The following steps are repeated during the course of an Enterprise Agent's operation.

1. Wake up
2. Resolve assigned collector hostname
3. Determine operating system and kernel versions
4. Handshake with the agent collector
5. Check for results which have not yet been synchronized with the agent collector
6. Synchronize with the agent collector
7. Check current version against available version
   1. if version is out of date, initiate background update process
   2. determine next available window to apply updates
   3. apply updates
8. Get new task information
9. Go back to sleep until the next task needs to be run

## Specific Test Information

The information is exchanged with the assigned agent collector; the type of information exchanged with the collector depends largely upon which kinds of tests are being run from the ThousandEyes agent. In essence, our focus is twofold. First, collection of timing information for each phase of a request, and second, information about each routable device (aka "node") touched in the path between the agent and the destination, and the links that connect these nodes.

### Network Data

Name, IP address, network prefix, and MPLS label information (if any), for each node encountered during a traceroute, as well as latency and MTU information for each link transited. This information is also included in test information for tests have the *enable network measurements* option checked.

From the example image above, when a network test is targeted for [www.saas.com](http://www.saas.com), timing, latency, jitter, and MTU info and identification info will be sent back for the following elements:

* The endpoint ([www.saas.com](http://www.saas.com), 1.2.3.4)
* Each node transited during the connection (r1, firewall, r2, r3, r4)
* Each link transited during the connection (l1, l3, l4, l5, l6, l7)

### HTTP Server Data

Name, IP address, number of redirects, fetch timing, HTTP status codes and response headers for the target site. Includes network data if the *enable network measurements* option is checked.

From the example image above, when an HTTP server test is targeted for [http://internalweb](/product-documentation/global-vantage-points/enterprise-agents/data-collected-by-enterprise-agents), the following information will be sent back:

* Network information (Endpoint=[http://internalweb](/product-documentation/global-vantage-points/enterprise-agents/data-collected-by-enterprise-agents), 10.0.0.1, nodes=r1, links=l1, l2)
* Http status code, response headers and timing for the attempt to access the website.

### Page Load Data

Includes HTTP Server data, plus an HTTP archive (using HAR output spec) for page load, which includes detailed timing and descriptive information for each component on the page. A HAR file is a container which contains a lot of information, and may include the following details:

* Name and path of the agent
* how long it takes to fetch DNS information
* how long each object takes to be requested
* how long it takes to connect to the server
* how long it takes to transfer each object from the server to the browser
* whether or not the object is blocked

The HAR output specification can be found here: <http://www.softwareishard.com/blog/har-12-spec/>. To generate a HAR file for yourself (or see a sample file) and investigate the contents of the file, see [this article](https://docs.thousandeyes.com/product-documentation/advanced-troubleshooting/how-to-generate-a-har-file).

From the example image above, when a page load test is attempted against [www.saas.com](http://www.saas.com), the following information will be sent back:

* Network data (Endpoint = [www.saas.com](http://www.saas.com), 1.2.3.4, nodes=r1,firewall,r2,r3,r4, links=l1,l3,l4,l5,l6,l7)
* HTTP Server data (status code, response headers, timing)
* Page load data (HAR file containing detailed timing and descriptive information about each component on the page)

### Transaction Data

Includes page load data (HAR content) for each step page visited during execution of the transaction. Transactions do not include network or HTTP server information.

### DNS Trace Data

Output from dig +trace from the Enterprise Agent to the destination DNS record

From the example image above, when a DNS trace is attempted against [www.saas.com](http://www.saas.com) A, the following information will be returned:

```
. 18501 IN NS c.root-servers.net.
(...)
. 18501 IN NS d.root-servers.net.
;; Received 228 bytes from 8.8.8.8#53(8.8.8.8) in 919 ms
com. 172800 IN NS c.gtld-servers.net.
(...)
com. 172800 IN NS d.gtld-servers.net.
;; Received 490 bytes from 202.12.27.33#53(202.12.27.33) in 6797 ms
saas.com. 172800 IN NS ns2.servervault.com.
saas.com. 172800 IN NS ns1.servervault.com.
;; Received 110 bytes from 192.31.80.30#53(192.31.80.30) in 502 ms
www.saas.com. 3600 IN A 216.12.130.234
saas.com. 300 IN NS ns1.servervault.com.
saas.com. 300 IN NS ns2.servervault.com.
;; Received 126 bytes from 216.36.34.197#53(216.36.34.197) in 38 ms
```

### DNS Server Data

IP mapping, timing and errors against each authoritative DNS server selected in the test configuration.

From the example image above, when a DNS server test is attempted for [www.saas.com](http://www.saas.com) A, the following information will be returned:

* Authoritative nameservers for the DNS record (ns1.servervault.com, ns2.servervault.com), plus associated IP addresses for those servers
* Average availability, error count and resolution time from the Enterprise Agent to the nameservers

### DNSSEC Trace Data

Trust tree and data chain information for each nameserver returned in a DNSSEC query, validated from the bottom of the chain up. DNSSEC data will not apply to most customers. For DNSSEC data, please see [this article](https://docs.thousandeyes.com/product-documentation/thousandeyes-basics/using-the-dns-dnssec-trace-view) for more information.

### Voice Data

Voice metric data (if the Enterprise Agent is the target of the voice test) and path visualization data.

### Other Test Data

BGP tests do not use Enterprise Agents.

## Data Storage

During a test, and between check-ins with the agent collector, the Enterprise Agent stores all information locally, before uploading to the collector. Once the information has been synchronized with the collector, it is removed from the agent.

If the Enterprise Agent can't contact the ThousandEyes collectors, ThousandEyes will store the data locally for 36 hours before removing it from the agent.

## Security Controls

At ThousandEyes, we implement a number of policies and controls to ensure that customer information is protected from unauthorized access, including the following:

* Information Security policies and standards regulate the business processes and set acceptance criteria for information systems;
* Technical access controls are enforced at the application, system, and network layers;
* Logical data segregation is implemented at the application layer, all data elements are linked to a specific customer and may not be accessible to other customers.


# Enterprise Agent Support Lifecycle

In order to ensure proper and consistent data collection, ThousandEyes Enterprise Agents require up-to-date agent software, running on a fully supported operating system. As operating system providers end support for versions of their operating systems, ThousandEyes will reduce or end support for Enterprise Agents on those operating systems.

This article details the ThousandEyes support policy and notification methods, the stages of the ThousandEyes Enterprise Agent operating system and software support lifecycle, and the relevant end of life/support dates for each supported operating system.

## ThousandEyes Support Lifecycle Policy

ThousandEyes will take reasonable measures to provide customers with at least 90 days' advance notice in the event that any features or functions of the ThousandEyes service are deprecated or removed, if the removal of the feature may negatively impact a customer's use of the service. Notifications will be made via the [Changelog](https://docs.thousandeyes.com/whats-new/changelog), as well as via email to any relevant [email subscribers](https://docs.thousandeyes.com/product-documentation/getting-started/notification-of-upgrades-maintenance-and-outages#subscribing-to-email-notifications).

{% hint style="warning" %}
ThousandEyes may make modifications on less than 90 days' advance notice if required to fix a security issue.
{% endhint %}

ThousandEyes reserves the right to modify this policy at our discretion.

### Notifications

For Enterprise Agents that have reached a new lifecycle phase, the **Operating System** text in the agent's entry in the [Enterprise Agent Settings](https://app.thousandeyes.com/network-app-synthetics/agent-settings/enterprise/?section=agents) page of the ThousandEyes application will be displayed in red, with a link to the relevant upgrade documentation.

{% hint style="info" %}
For an explanation of each lifecycle phase, see [Support Lifecycle Phases](#support-lifecycle-phases).
{% endhint %}

Approaching lifecycle phases are announced in the [changelog](https://docs.thousandeyes.com/whats-new/changelog) entries that accompany ThousandEyes software releases. Software releases typically occur every two weeks. Notification of an approaching phase change will appear in at least one changelog entry, typically at least a month in advance of the announced date.

For instructions on subscribing to email notifications, see [Subscribing to Email Notifications](https://docs.thousandeyes.com/product-documentation/getting-started/notification-of-upgrades-maintenance-and-outages#subscribing-to-email-notifications).

### Enterprise Agent Software Support

ThousandEyes provides technical support and software updates for issues found in versions of the Enterprise Agent software issued within six months of the most recent release date of agent software. To obtain fixes for Enterprise Agent software, customers must upgrade to the most recent version of Enterprise Agent software. Enterprise Agents normally perform software updates automatically when ThousandEyes makes an update available.

### Operating System Support

ThousandEyes Enterprise Agents run on either the Ubuntu Linux distribution, or the Red Hat Enterprise Linux distribution (along with the AlmaLinux and Oracle Linux variations of Red Hat Enterprise Linux). The ThousandEyes support lifecycle contains four phases that are based on the supported Ubuntu Linux Long Term Support (LTS) versions and the Red Hat Enterprise Linux versions currently in either the **Full Support Phase** or the subsequent **Extended Update Support** (EUS) period.

{% hint style="info" %}
For more information about either Ubuntu or Red Hat release versions and support periods, see either [Ubuntu Releases](https://wiki.ubuntu.com/Releases) or [Red Hat Enterprise Linux Life Cycle](https://access.redhat.com/support/policy/updates/errata).
{% endhint %}

### Support Lifecycle Phases

There are four phases in the ThousandEyes support lifecycle:

* Full Support
* End of Installation Support
* End of Support
* End of Life

#### End of Installation Support

In the **End of Installation Support** (EIS) phase, ThousandEyes will remove the ability to install Enterprise Agents on a version of an operating system. This occurs 90 days prior to the **End of Support** phase.

{% hint style="info" %}
For some Red Hat Enterprise Linux minor versions, the End of Installation Support date is aligned with the End of Support date instead. See [RHEL Support Lifecycle](#red-hat-enterprise-linux-almalinux-oracle-linux) for details.
{% endhint %}

{% hint style="info" %}
For Rocky Linux, the End of Installation Support date is aligned with the End of Support date instead. See [Rocky Linux Support Lifecycle](#red-hat-enterprise-linux-almalinux-oracle-linux) for details.
{% endhint %}

#### End of Support

In the **End of Support** (EoS) phase, ThousandEyes will no longer provide technical support nor guarantee software updates (including bug fixes) for customers running Enterprise Agents on the affected version of an operating system. Agents may continue to commit test data to the ThousandEyes platform.

#### End of Life

**End of Life** (EoL) occurs 60 days after the **End of Support** phase begins. Agents will no longer be able to communicate with the ThousandEyes platform, and will self-terminate with an error message.

#### Example Operating System Support Lifecycle

The diagram below uses Ubuntu Linux version 14.04 LTS to illustrate the three phases of the ThousandEyes lifecycle. Support for version 14.04 LTS ended in April, 2019:

![](/files/-M62_TcxNFXVO-5klDNV)

## Operating System Lifecycle Phase Dates

The sections and tables below provide the upcoming lifecycle phase change dates for each currently supported operating system version.

### Ubuntu Linux

ThousandEyes only supports Ubuntu Linux long term support (LTS) versions. Ubuntu supports LTS versions for five years after the release date. Once the Enterprise Agent software is released for a specific LTS version, ThousandEyes will align the start of its End of Support phase with the operating system's End of Life date, as defined by Ubuntu.

The Ubuntu Wiki [Releases](https://wiki.ubuntu.com/Releases) page lists their **End of Life** dates. The corresponding ThousandEyes lifecycle dates are listed below, using YYYY-MM-DD.

| Operating System Version                                                 | End of Installation Support | End of Support | End of Life |
| ------------------------------------------------------------------------ | --------------------------- | -------------- | ----------- |
| <p>Ubuntu 22.04 LTS (“Jammy”)</p><ul><li>x86\_64</li><li>ARM64</li></ul> | 2027-01-31                  | 2027-04-30     | 2027-06-30  |
| <p>Ubuntu 24.04 LTS (“Noble”)</p><ul><li>x86\_64</li><li>ARM64</li></ul> | 2029-01-31                  | 2029-04-30     | 2029-06-30  |

### Red Hat Enterprise Linux / Oracle Linux / Rocky Linux / AlmaLinux

ThousandEyes supports versions of Red Hat-based operating systems that are eligible for Red Hat's [Extended Update Support Subscription](https://access.redhat.com/solutions/22763), in alignment with the official Red Hat support lifecycle. This policy applies to compatible distributions, including Oracle Linux, Rocky Linux, and AlmaLinux.

{% hint style="warning" %}
On Oracle Linux systems, the Enterprise Agent may identify and report the operating system as Red Hat Enterprise Linux due to binary compatibility and shared package lineage across Red Hat-compatible distributions.
{% endhint %}

{% hint style="info" %}
In most cases, ThousandEyes bases support for versions of Red Hat Enterprise Linux and Oracle Linux on Red Hat's EUS subscription schedule. ThousandEyes will end support for the major version (i.e. all minor versions including the most recent minor version) at the expiration of EUS for the last eligible minor version.
{% endhint %}

{% hint style="info" %}
For Red Hat Enterprise Linux minor versions that do not have Extended Update Support (EUS) offered, ThousandEyes aligns the End of Installation Support date with the End of Support date to ensure customers have sufficient time to install new ThousandEyes agents on these versions until the date of upstream End of Life.

For more information about the Red Hat EUS, see [RHEL Extended Update Support](https://access.redhat.com/support/policy/updates/errata#Extended_Update_Support_RHEL).
{% endhint %}

For more information on the EUS-eligible versions and EUS end dates, see [Red Hat Enterprise Linux Life Cycle](https://access.redhat.com/support/policy/updates/errata). The corresponding ThousandEyes lifecycle dates are listed in the sections below.

#### Red Hat Enterprise Linux / Oracle Linux 8

| Operating System Version | End of Installation Support | End of Support | End of Life |
| ------------------------ | --------------------------- | -------------- | ----------- |
| 8.1                      | 2021-08-31                  | 2021-11-30     | 2022-01-30  |
| 8.2                      | 2022-01-31                  | 2022-04-30     | 2022-06-30  |
| 8.3 (non-EUS[^1])        | 2021-10-02                  | 2021-12-31     | 2022-03-01  |
| 8.4                      | 2023-03-01                  | 2023-05-30     | 2023-07-29  |
| 8.5 (non-EUS[^1])        | 2022-01-30                  | 2022-04-30     | 2022-06-29  |
| 8.6                      | 2024-03-01                  | 2024-05-31     | 2024-07-30  |
| 8.7 (non-EUS[^1])        | 2023-04-30                  | 2023-04-30     | 2023-06-29  |
| 8.8                      | 2025-03-01                  | 2025-05-31     | 2025-07-30  |
| 8.9 (non-EUS[^1])        | 2024-05-31                  | 2024-05-31     | 2024-07-30  |
| 8.10                     | 2029-03-02                  | 2029-05-31     | 2029-07-30  |

#### Red Hat Enterprise Linux / Oracle Linux 9

| Operating System Version | End of Installation Support | End of Support | End of Life |
| ------------------------ | --------------------------- | -------------- | ----------- |
| 9.0                      | 2024-03-02                  | 2024-05-31     | 2024-07-30  |
| 9.2                      | 2025-03-02                  | 2025-05-31     | 2025-07-30  |
| 9.3 (non-EUS[^1])        | 2024-03-02                  | 2024-05-31     | 2024-07-30  |
| 9.4                      | 2026-01-30                  | 2026-04-30     | 2026-06-29  |
| 9.5 (non-EUS[^1])        | 2025-04-30                  | 2025-04-30     | 2025-06-29  |
| 9.6                      | 2027-03-01                  | 2027-05-30     | 2027-07-29  |
| 9.7 (non-EUS[^1])        | 2026-04-30                  | 2026-04-30     | 2026-06-29  |
| 9.8                      | 2028-03-01                  | 2028-05-30     | 2028-07-29  |
| 9.9 (non-EUS[^1])        | 2027-04-30                  | 2027-04-30     | 2027-06-29  |
| 9.10                     | 2032-03-02                  | 2032-05-31     | 2032-07-30  |

#### Rocky Linux 9

| Operating System Version | End of Installation Support | End of Support | End of Life |
| ------------------------ | --------------------------- | -------------- | ----------- |
| 9.3                      | 2024-05-30                  | 2024-05-30     | 2024-07-29  |
| 9.4                      | 2024-11-30                  | 2024-11-30     | 2025-08-12  |
| 9.5                      | 2025-05-30                  | 2025-05-30     | 2025-07-29  |
| 9.6                      | 2025-11-30                  | 2025-11-30     | 2026-01-29  |
| 9.7                      | 2026-05-30                  | 2026-05-30     | 2026-07-29  |
| 9.8                      | 2026-11-30                  | 2026-11-30     | 2027-01-29  |

#### AlmaLinux

ThousandEyes bases our support lifecycle dates for AlmaLinux major releases on those published here: [AlmaLinux Release Notes](https://wiki.almalinux.org/release-notes/). AlmaLinux minor versions reach end of life when the next minor version is released (see the AlmaLinux documentation linked previously for more information).

Customers are expected to maintain the auto-upgrade setting to ensure they are using the latest minor version, which can be done by keeping the defeault configuration of "dnf upgrade".

{% hint style="warning" %}
Enterprise Agents installed on servers that are not running the latest minor version will not be supported.
{% endhint %}

| Operating System Version | End of Installation Support | End of Support | End of Life |
| ------------------------ | --------------------------- | -------------- | ----------- |
| AlmaLinux 8.x            | 2029-02-28                  | 2029-05-31     | 2029-07-31  |
| AlmaLinux 9.x            | 2032-02-28                  | 2032-05-31     | 2032-07-31  |

### Alpine Linux

{% hint style="warning" %}
ThousandEyes Docker-based Enterprise Agents, and Cisco devices using Cisco Application Hosting are built on Alpine Linux. However, ThousandEyes does not support the native installation of ThousandEyes Enterprise Agents on Alpine Linux.
{% endhint %}

| Operating System Version | End of Installation Support | End of Support | End of Life |
| ------------------------ | --------------------------- | -------------- | ----------- |
| 3.20                     | 2026-01-01                  | 2026-04-01     | 2026-06-01  |
| 3.21                     | 2026-08-01                  | 2026-11-01     | 2027-01-04  |

### Amazon Linux

ThousandEyes will provide support for Amazon Linux until the operating system reaches **End of Life**, as defined by Amazon. For more information, see [Amazon Linux 2 FAQs](https://aws.amazon.com/amazon-linux-2/faqs/).

{% hint style="warning" %}
Browserbot is not supported on Amazon Linux installations.
{% endhint %}

The corresponding ThousandEyes lifecycle dates are listed below.

| Operating System Version | End of Installation Support | End of Support | End of Life |
| ------------------------ | --------------------------- | -------------- | ----------- |
| Amazon Linux 2           | 2026-03-30                  | 2026-06-30     | 2026-08-30  |
| Amazon Linux 2023        | 2027-03-31                  | 2027-06-30     | 2027-08-31  |

[^1]: For some Red Hat Enterprise Linux minor versions, the End of Installation Support date is aligned with the End of Support date instead. See [RHEL Support Lifecycle](https://access.redhat.com/support/policy/updates/errata) for details.


# Enterprise Agent Installation

ThousandEyes Enterprise Agents can be installed in several different ways depending on your existing infrastructure and technical preferences. Before you begin, review the installation prerequisites below and the system requirements and supported operating systems in [Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents).

## Installation Prerequisites

Before you install an Enterprise Agent, verify that you have the following:

* **Account group token**: You need an installation token to register the agent with your ThousandEyes account. You can find this token in the ThousandEyes platform on the [Agent Settings page](https://docs.thousandeyes.com/product-documentation/global-vantage-points/working-with-agent-settings) or the [Account Settings page](https://docs.thousandeyes.com/product-documentation/user-management/authorization/account-groups/working-with-account-settings).
* **Minimum Hardware Requirements**: The host machine must meet the minimum hardware requirements needed to run the agent. See [Common System Requirements](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents#common-system-requirements).
* **Network and internet connectivity**: The host machine must have a stable network connection with outbound internet access to reach the ThousandEyes platform, execute tests, and report results. The system must be configured with at least one assigned IPv4 or IPv6 address on an active network interface, with appropriate routing and firewall policies to support agent communication and monitoring operations. See [Firewall Configuration for Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/firewall-configuration-for-enterprise-agents) for a complete list of required rules.
* **Infrastructure services**: The agent requires access to a Domain Name System (DNS) service to resolve hostnames and a Network Time Protocol (NTP) service to maintain accurate system time.

## Deployment Methods

### Linux Package

* [Linux Package Agent Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/linux-package-agent-installation)

### Docker Container

* [Docker-Based Agent Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/docker-based-agent-installation)

### Virtual Appliance

* [ThousandEyes Virtual Appliance (TEVA) Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-virtual-appliance-installation)

### Physical Appliance

* [ThousandEyes Physical Appliance (TEPA) Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-physical-appliance-installation)

### Cisco Devices

* [Cisco Catalyst Routers](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/catalyst-routers)
* [Cisco Catalyst Switches](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/catalyst-switches)
* [Cisco Industrial Ethernet Switches](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/industrial-ethernet-switches)
* [Cisco Industrial Routers](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/industrial-routers)
* [Cisco Meraki MX Appliances](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/meraki)
* [Cisco Nexus Switches](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/nexus-switches)
* [Cisco Enterprise NFVIS](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/nfvis)
* [Cisco Service Routers](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/service-routers)


# ThousandEyes Virtual Appliance (TEVA) Installation

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:

1. 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
2. Configure the virtual appliance

### Importing the Virtual Appliance

#### Resource Locations

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**

  ![](/files/-M5xtPtBWZ6w729248Qi)
* 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.

  ![](/files/-M5xtPtEy2A98Eh2kCfz)

#### Import with the Open Virtualization Format (OVA)

1. Download the latest [thousandeyes-va-\<version>.ova](https://app.thousandeyes.com/install/downloads/appliance/thousandeyes-appliance.ova) file from the **Network & App Synthetics > Agent Settings > Enterprise Agents > Agents** page.
2. Click **Add New Enterprise Agent** on the left side of the **Agent Settings** screen.
3. 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.
4. 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.

   ![](/files/-M5xtPtH5-nqgIWjsJQk)
5. 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](http://www.virtualbox.org/manual/ch01.html#ovf)
   * [VMware Fusion version 10.x and later](https://docs.vmware.com/en/VMware-Fusion/index.html)
   * [VMware Workstation version 14.x and later](https://docs.vmware.com/en/VMware-Workstation-Pro/index.html)
   * [VMware ESXi version 6.5 and later](https://docs.vmware.com/en/VMware-vSphere/index.html)
   * [Microsoft Hyper-V](https://docs.thousandeyes.com/product-documentation/enterprise-agents/enterprise-agent-deployment-using-thousandeyes-virtual-appliance-hyper-v)
   * [Nutanix AHV managed by Prism Central version 7.3.1.1 and later](https://portal.nutanix.com/page/documents/details?targetId=Prism-Central-Guide-vpc_7_5:mul-ova-upload-pc-t.html).

   **Note:** Nutanix AHV is supported with Legacy BIOS Mode with DISK (SCSI.0) in boot configuration only.
6. 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**](https://kb.vmware.com/s/article/1001805) **adapter type is recommended. Flexible adapters are currently not supported.**
7. Configure the virtual appliance.

![Imported OVA appearing in VirtualBox](/files/-M62_WKa-ScbS8QBnQCN)

![Network Settings showing Bridged Adapter selected](/files/-M62_WKgWOF12t9AGzwr)

![Virtual Appliance View following Start](/files/-M62_WKm_bUBPww3Htsj)

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

#### Import with the Microsoft Hyper-V Format

1. The instructions below use Hyper-V Manager from Windows Server 2016, but the steps are similar for other supported versions of Hyper-V.
2. Download the latest [thousandeyes-va-\<version>.zip ](https://app.thousandeyes.com/install/downloads/appliance/thousandeyes-appliance.zip)file from the **Network & App Synthetics > Agent Settings > Enterprise Agents > Agents** page.
3. Click **Add New Enterprise Agent** on the left side of the **Agent Settings** screen.
4. 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.
5. 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.
6. Run Hyper-V Manager and click on "Import Virtual Machine...".
7. 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".
8. 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.

   ![](/files/-M62_WKrtdvhToBehJe9)
9. After the virtual machine has been imported, click "Settings...".
10. Select "Network Adapter" from the left pane.
11. 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.

![](/files/-M62_WKzBdBrwe06PehY)

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

![](/files/-M62_WL5yhvZEkYaUSPN)

14. Configure the virtual appliance.

### Configuring the Virtual Appliance

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

1. After the system starts, a screen will appear that will show and IP address for the management console and default access credentials
2. Access the ThousandEyes virtual appliance interface through the URL in that screen and login with the credentials shown.

   ![](/files/-M62_WL9jWn0K6SOPF7N)

   Press **N** to access manual network configuration. For specific configuration steps, see [Advanced Network Settings](#advanced-network-settings).
3. Open a browser entering the URL presented on the screen. Enter the default username and password given.

   ![](/files/-M62_WLJL1qYnnKT-h52)
4. Change the virtual appliance management console Web Interface Password, and click **Change Password**.

   ![](/files/-M62_WLOo2SUhJhfCd27)
5. 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.
6. Retrieve the Account Group token from **Network & App Synthetics > 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.

   ![](/files/-M62_WLTUXPDvXQ0g0OC)
7. Paste the Account Group Token into the Account Token field. The field should turn green.

   ![](/files/-M62_WLWgTE0SxxARAQb)
8. Yes is selected for Browserbot by default since this component is required for Page Load and Transaction test types.
9. Click **Continue**.
10. 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.
11. 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.
12. 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.
13. The **Network** section of the Web Interface will be shown. Select the **Status** section once more and click **Run Diagnostics**.
14. Flipping back to the **Agent Settings** page, the Agent Status in the Listing should show Status/Last Contact in yellow.
15. 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: **Network & App Synthetics > 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

  ![](/files/6HHQsoZUk8HiwPqBEuis) ![](/files/5mYmpKGoRp2D7wUhhS23) ![](/files/Q2YK7u1hSd6EK1hZbJWj)
* Run diagnostics

  ![](/files/-M62_WLv539B0qCs72B3)
* Check status

  ![](/files/-M62_WM-N2tn_3s_Mgmk) ![](/files/-M62_WM3kY2cg45f71PT)
* Check for green online status

  ![](/files/-M62_WM87Eg1kiQWxysH) ![](/files/-M62_WMBjRjMBJkMk7Hh)

## 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.

{% hint style="info" %}
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.
{% endhint %}

### Unattended Upgrade Reboot Schedule Configuration

Unattended upgrades allow for base OS security patches to be applied automatically. When required, the host will reboot to complete the patch application. You can configure the preferred timing for these reboots to align with your environment's maintenance windows by setting the day, time, and frequency (daily or weekly) of the upgrades. When an unattended upgrade takes place, the system will delay the reboot until the scheduled time.

![](/files/druaseMuAlk4dobsBAIW)

## Custom Virtual Appliances

ThousandEyes has introduced the ability to download a custom Virtual Appliance. Purpose-built for organizations deploying Virtual Appliances to clients, the custom Virtual Appliance is pre-configured with the account token and SSH keys used for management of the appliance. This streamlines configuration management and eliminates complexity for organizations deploying large numbers of virtual Appliances.

To generate a custom Virtual Appliance, go to **Network & App Synthetics > Agent Settings**, **Add New Agent**, and select the **Custom Appliance** tab, then select the **Virtual** tab:

![](/files/-M5xtIcMvMCGT5YLelCT)

Give the Virtual Appliance a name, select a format per the list below, select if you want the Web Server and add **public SSH keys** as appropriate:

* **ova** - our most popular VA offering, formatted for use in VMware products, XenServer and VirtualBox.
* **zip** - for use with Microsoft Hyper-V server 2008
* **Cisco OVA** - for use within Cisco IOS XE based Integrated Service Routers (ISR)/Aggregated Service Routers (ASR)

Once you click the **Generate** button, it will take up to 30 minutes to generate a Virtual Appliance, depending on the format requested. You will receive an email when the generation process is complete.

## Related Articles

* To know more about Enterprise Agent hardware recommendations, see [Enterprise Agent Hardware Requirements](https://docs.thousandeyes.com/product-documentation/enterprise-agents/enterprise-agent-hardware-requirements).
* For recommended firewall configurations, see [Firewall Configuration for Enterprise Agents](https://docs.thousandeyes.com/product-documentation/enterprise-agents/firewall-configuration-for-enterprise-agents).
* For Enterprise Agent proxy options, see [Configuring an Enterprise Agent to Use a Proxy Server](https://docs.thousandeyes.com/product-documentation/enterprise-agents/configuring-an-enterprise-agent-to-use-a-proxy-server) article.
* This article explains process of [Installing Enterprise Agent on VirtualBox](#importing-the-virtual-appliance-into-virtualbox).
* Gaining access to ThousandEyes Appliance using SSH from [Mac/Linux](https://docs.thousandeyes.com/product-documentation/enterprise-agents/connecting-to-the-thousandeyes-virtual-appliance-using-ssh-mac-linux) and [Windows](https://docs.thousandeyes.com/product-documentation/enterprise-agents/connecting-to-the-thousandeyes-virtual-appliance-using-ssh-windows).


# ThousandEyes Physical Appliance (TEPA) Installation

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

For customers requiring a turnkey solution, the ThousandEyes [Enterprise Agent](https://docs.thousandeyes.com/product-documentation/enterprise-agents/what-is-an-enterprise-agent) can be installed on off-the-shelf hardware such as

* ASUS / Intel NUC
* Raspberry Pi

  For Raspberry Pi-specific instructions, see [this article](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/raspberry-pi-agent-installation).

The combination provides a convenient form-factor that is easily shipped to branch offices, partner sites, and other environments, where provisioning only requires power and a network connection. A downloadable ISO image is used to install Linux Ubuntu LTS, the ThousandEyes Enterprise Agent, and management software onto the hardware.

## ASUS and Intel NUC

This article details the hardware requirements and process required to install the ThousandEyes Enterprise Agent on an ASUS or Intel NUC.

## NUC Hardware Validation Policy

* ThousandEyes explicitly lists and supports only the validated models of ASUS and Intel NUC hardware.
* Any other ASUS or Intel NUC models in the same generation that meet or exceed the specified minimum memory and storage requirements (at least 2GB RAM and 20GB SSD/NVMe storage) are expected to be compatible with the ThousandEyes Enterprise Agent. See [Enterprise Agent Hardware Requirements](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents) for common hardware requirements for all ThousandEyes appliances.
* However, it is the sole responsibility of the customer to perform thorough validation and testing of any non-validated NUC models they intend to deploy to ensure full compatibility and performance.
* Customers are strongly encouraged to adhere to the validated model list to guarantee optimal support and reliability.

## Hardware Requirements

### ASUS NUC 15th Generation

| Subsystem | Manufacturer | Component  | Validated Models |
| --------- | ------------ | ---------- | ---------------- |
| NUC       | ASUS         | NUC 15 Pro | NUC15CRKU7       |

| Part Numbers | Memory                                                                                                                                                                                                                                                                    | Disk                                                                                                                                                                                                                                                                         |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NUC15\*      | Any memory configuration supported by the NUC. A minimum of 2GB, as specified in [Enterprise Agent Hardware Requirements](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/enterprise-agent-hardware-requirements). | Any single SSD or NVMe disk supported by the NUC. A minimum of 20GB as specified in [Enterprise Agent Hardware Requirements](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/enterprise-agent-hardware-requirements). |

### ASUS NUC 14th Generation

| Subsystem | Manufacturer | Component  | Validated Models |
| --------- | ------------ | ---------- | ---------------- |
| NUC       | ASUS         | NUC 14 Pro | NUC14RVK-B       |

| Part Numbers | Memory                                                                                                                                                                                                                                                                    | Disk                                                                                                                                                                                                                                                                         |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NUC14\*      | Any memory configuration supported by the NUC. A minimum of 2GB, as specified in [Enterprise Agent Hardware Requirements](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/enterprise-agent-hardware-requirements). | Any single SSD or NVMe disk supported by the NUC. A minimum of 20GB as specified in [Enterprise Agent Hardware Requirements](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/enterprise-agent-hardware-requirements). |

### Intel NUC 13th Generation

| Subsystem | Manufacturer | Component            | Validated Models |
| --------- | ------------ | -------------------- | ---------------- |
| NUC       | Intel        | NUC i7 NUC i5 NUC i3 | RNUC13ANHI70000  |

| Part Numbers | Memory                                                                                                                                                                                                                                                                    | Disk                                                                                                                                                                                                                                                                         |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NUC13\*      | Any memory configuration supported by the NUC. A minimum of 2GB, as specified in [Enterprise Agent Hardware Requirements](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/enterprise-agent-hardware-requirements). | Any single SSD or NVMe disk supported by the NUC. A minimum of 20GB as specified in [Enterprise Agent Hardware Requirements](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/enterprise-agent-hardware-requirements). |

### Obsolete Intel NUC Generations (8th, 10th, 11th, 12th)

**NOTICE:** Obsolete Intel NUC generations are only supported for existing deployments.

| Generation      | Validated Models                                                                                                       |
| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| 12th Generation | NUC12WSHi5                                                                                                             |
| 11th Generation | NUC11TNHi3, NUC11TNHi5, NUC11TNHi7, NUC11TNHv5, NUC11TNHv7, NUC11TNKi3, NUC11TNKi5, NUC11TNKi7, NUC11TNKv5, NUC11TNKv7 |
| 10th Generation | NUC10i7FNH, NUC10i7FNK, NUC10i5FNH, NUC10i5FNK, NUC10i3FNH, NUC10i3FNK, BXNUC10i5FNH1, BXNUC10i3FNH1, BXNUC10i7FNH1    |
| 8th Generation  | NUC8I7BEH, NUC8I5BEH, NUC8I5BEK, NUC8I3BEH, NUC8I3BEK                                                                  |

* **Memory:** Any memory configuration supported by the NUC. A minimum of 2GB, as specified in [Enterprise Agent Hardware Requirements](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/enterprise-agent-hardware-requirements).
* **Disk:** Any single SSD or NVMe disk supported by the NUC. A minimum of 20GB as specified in [Enterprise Agent Hardware Requirements](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/enterprise-agent-hardware-requirements).

## Installation Environment Requirements

The following are required:

* **Wired network connection:** The device must be connected to a network. Wireless connections are not supported.

  **Note:** When the NUC is powered off and it is connected to an operational Ethernet switch, the LED on the lower right of the RJ-45 port on the NUC will be lit. This indicates that a link signal from the switch is active.
* **Dynamic Address Assignment:** A DHCP service or SLAAC must be available for the device to obtain an IP address.
* **DNS service:** The DHCP service must provide DNS server information to the device.
* **Non-proxied and unrestricted access to the internet:** The installation process downloads several software packages from online resources. Refer to [Enterprise Agent Firewall Requirements](https://docs.thousandeyes.com/product-documentation/enterprise-agents/firewall-configuration-for-enterprise-agents) for the list of online locations.

The *Troubleshooting* section below lists common issues and their resolution.

## Downloading the Installer

Download the installer that fits the requirement:

* Generic Appliance. There are no pre-configurations.
* Custom Appliance. Includes Enterprise Agent pre-configurations.

#### Generic Appliance

On the ThousandEyes platform, go to **Network & App Synthetics > Agent Settings**, select **Enterprise Agents** (top line), click **Add New Enterprise Agent** button. Select Package Type **Appliance.** On **Physical Appliance Installer** click **Download - ISO**.

![](/files/-M62_RB6AydUnfJAyQH3)

#### Custom Appliance

On the ThousandEyes platform, go to **Cloud & Enterprise Agents> Agent Settings**, select **Enterprise Agents** (top line), click **Add New Enterprise Agent**. Select Package Type **Custom Appliance**. Provide the following information:

* **Appliance Name**. Name of the appliance on the ThousandEyes systems and the Linux host name.
* **Appliance Type**, select Physical.
* If required, select **Add Proxy** and specify the Proxy Host and Proxy Port.
* **Web Server**. If the appliance is to be used for Page Load or Transaction test, select On.
* **SSH Keys**. The **SSH Public key** of the SSH client to be used to access the appliance, for terminal session.

Note that the custom download will include the account group token required for the Agent to register itself to the ThousandEyes system.\
Click **Generate**. It may take take between 15 and 30 minutes to generate the image. An email will be generated once the image is ready to be downloaded.

![](/files/-M62_RBBBrPW4s1Kus9Z)

## ASUS and Intel NUC BIOS

The following are intended to be a check list of configurations required for the ThousandEyes application. You should consult the appropriate ASUS or Intel documentation for the applicable procedures.

* Intel documentation can be found [here](https://www.intel.com/content/www/us/en/support/articles/000005636/mini-pcs.html).
* BIOS update files for the Intel NUC can be found [here](https://downloadcenter.intel.com/search?keyword=bios+nuc).
* ASUS NUC documentation and BIOS updates can be found on the [ASUS support site](https://www.asus.com/support/).
* Check that the display (monitor) used with the NUC are compatible. Check on the hardware documentation. To verify, power up the NUC with the monitor connected, if the manufacturer splash screen can be seen, the monitor is compatible.
* On the NUC, check that the BIOS version is current. If not the most current, upgrade to the latest version.
* The appliance is intended to the an always-on device. Verify that the following is set in the BIOS:
  * After Power Failure setting should be set to Last State or Power On.

## Installing Physical Appliance Software

1. Verify that the installation environment requirements are satisfied.
2. Insert the bootable USB disk in one of the USB slots on the NUC.
3. Power up the NUC.
4. Tap the **F10** key (on the keyboard) to force the BIOS to enter the "Boot" menu.
5. On the boot device menu, use the arrow keys to select the USB drive and press **Enter**.

If USB is not shown as an option, power off the NUC, unplug the USB drive, plug it back in and power up the NUC.

**Note:** The BIOS will recognize the USB drive as a bootable device even if the USB flash drive is blank (nothing in it). If the BIOS does not recognize the USB drive as a valid bootable device, when there is a USB flash drive inserted, check that the BIOS version is current. If not current upgrade to the latest version.

6. On booting from the USB drive, the installation process will start automatically. `No` user intervention is required, The initial phase will progress fairly quickly, a progress bar will narrate the progress. The final phase is shown by the "Finishing the installation" screen, "Running preseed," the progress bar will show "14%." The installation process are downloading the required software packages. This screen may remain in this state for about 15 minutes, depending on the speed of the network interface and the delays to the download server. Do not power off the NUC. Leave it until it automatically powers off.
7. On completing the installation, the NUC will automatically power off.
8. Remove the installation USB.

   If you don't remove it once the installation is complete, the NUC attempts to boot again, restarting the installation process.

## Configuring the Enterprise Agent

See [ThousandEyes Virtual Appliance Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-virtual-appliance-installation) for a comprehensive set of instructions. The following are the minimum required to enable the Physical Agent to communicate with the ThousandEyes platform.

1. Power on the NUC. After the unit boots, the "ThousandEyes Virtual Appliance" screen (shown below) will be displayed. The IP address displayed depends on the network environment of the NUC. Note the provided username and password.

![](/files/-M62_RBbfNIgoFa710yG)

2. Using a browser, access the provided URL (IP address), and log in using the provided username and password.

![](/files/-M62_RBfw6mgzn1HqRn2)

3. The user will be taken to the **Appliance Access** screen to change the default password.

![](/files/-M62_RBlfweyTS9bNvWw)

4. Skip this step if the installation is a Custom Appliance, as the account group token is included in the image.

For a Generic Appliance installation, the account group token is obtained on the ISO download screen on the ThousandEyes portal, by clicking "Show Account Group Token for Installation."

![](/files/-M62_RBpT6Dqx49U5TA4)

On the **Agent** screen, copy the account group token to the field provided.

![](/files/-M62_RBtU3S_fUAyQbs8)

5. For information on the other parameters, see [ThousandEyes Virtual Appliance Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-virtual-appliance-installation).
6. Verify on the **Status** screen that all diagnostics are green. Follow up and correct any faults shown on the Status screen.

![](/files/-M62_RBx7jaE-CGt-ao3)

7. If network related parameters were changed, for example disabling IP V6 support, reboot the Agent, through the GUI and verify that all the diagnostics are green.

![](/files/-M62_RC07aaDn-zkxJFJ)

8. The Enterprise Agent should now appear in the **Cloud & Enterprise Agents> Agent Settings> Enterprise Agents** page of the ThousandEyes portal.

## Troubleshooting

#### USB Drive Not Recognized as a Bootable Device

A USB drive is plugged in, tapping F10 at power-up, on the "Boot" BIOS screen, USB drive is not recognized as a bootable device.

**Resolution:** Check that the BIOS version is current. If not current, upgrade to the latest version.

#### Malformed IP Address

Ubuntu installation fails with a "blue screen" showing "Malformed IP Address."

**Resolution:** Verify that the Ethernet connection to the NUC has a link signal. Verify that the Link LED on the RJ-45 port is lit.\
Verify that there is a DHCP server on the network (broadcast domain) that the NUC is connected to.

#### No Root File System Defined

Ubuntu installation fails with "No Root File System Defined" message. This situation can occur if USB devices are attached to the NUC via a USB hub.

**Resolution:** Do not use USB hub to connect keyboard and USB flash drive to the NUC.

#### "thousandeyes-va login:" Prompt Is Shown on the Screen

The expected blue "ThousandEyes Virtual Appliance" management screen is not displayed. 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.

**Resolution:** Components of the Virtual Agent are missing. Most likely caused by the lack of non-proxied and unrestricted access to the internet during the appliance installation. Reinstall the appliance in an environment that satisfies the requirements listed in the installation environment requirements.

#### Keyboard Not Working

When the installation completes, keypresses are not recognized.

**Resolution:** Most likely incomplete installation. Reinstall the appliance in an environment that satisfies the requirements listed in the installation environment requirements.

#### Do You Need Further Assistance?

For further assistance, contact [the ThousandEyes Customer Engineering team](https://docs.thousandeyes.com/product-documentation/getting-started/getting-support-from-thousandeyes).


# Docker-Based Agent Installation

ThousandEyes Enterprise Agents can be installed within a Docker container running a 64-bit Linux distribution, if the OS uses kernel version 3.10 or later, and supports both cgroups and network namespaces.

This article provides the installation instructions for Enterprise Agents in Docker containers.

{% hint style="warning" %}
Docker installations are considered a self-managed option. They can be used at your own risk, if your team has sufficient resources to manage the deployment.

As a part of container package best practices, we recommend updating your container regularly.
{% endhint %}

{% hint style="info" %}
ThousandEyes does not support Docker for macOS or Docker for Windows for production deployments.
{% endhint %}

## Prerequisites

Users will need the correct permissions to add new Enterprise Agents to the account group. For more information, see [Role-Based Access Control, Explained](https://docs.thousandeyes.com/product-documentation/user-management/rbac/role-based-access-control-explained).

{% hint style="warning" %}
The ThousandEyes for Government instance has additional requirements for Docker agent installations. Refer to the [ThousandEyes for Government - FedRAMP® Moderate](https://docs.thousandeyes.com/product-documentation/thousandeyes-for-government#docker-agent) documentation for prerequisites and configuration requirements **before** continuing.
{% endhint %}

## Deployment Options

You can choose between two different deployment options: the full Enterprise Agent (with BrowserBot for browser synthetics testing), or the base agent, that does not include BrowserBot.

{% hint style="info" %}
Additional system requirements (such as larger flash storage) are needed for BrowserBot installation (required for page load and transaction tests). ThousandEyes recommends performing a small proof-of-concept before committing to a larger deployment platform.
{% endhint %}

{% hint style="info" %}
Docker-based Enterprise Agents can be transitioned between including/not including BrowserBot via the command line. For instructions, see [Add / Remove BrowserBot from Existing Docker Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/docker-agents/add-remove-browserbot-from-existing-docker-enterprise-agents).
{% endhint %}

## Installing the Enterprise Agent Image

{% hint style="info" %}
The instructions below assume that you have installed and validated the Docker container.
{% endhint %}

1. Log into the ThousandEyes platform with a user account that has `edit agent` permissions.
2. Navigate to **Network & App Synthetics > Agent Settings**.
3. Click **Add New Enterprise Agent**.
4. Select the **Docker** tab.
5. Enter a name for your agent in the textbox. The agent name should not contain underscores or spaces.
6. Define the folder on the Docker host where persistent agent files will be stored (e.g. **/opt**). The folder will be created automatically upon agent instantiation, and log content will be sent here.
7. \[Optional] Select a proxy configuration by clicking **Static** or **PAC**, then input the relevant proxy information. For more information, see [Configuring an Enterprise Agent to Use a Proxy Server](https://docs.thousandeyes.com/product-documentation/enterprise-agents/configuring-an-enterprise-agent-to-use-a-proxy-server).
8. If you are installing the Enterprise Agent with BrowserBot, leave the **Install with BrowserBot support** box checked. If you wish to install only the base agent, uncheck the box.
9. Once these steps are completed, the code snippet/s will be updated with the set of commands you will need to copy and paste into the CLI of your Docker host. We recommend saving the commands locally, in case you need to reinstall the Docker image without changing the Enterprise Agent configuration.

The screenshot below shows an example configuration that includes BrowserBot:

![](/files/ZlQnmXeRYrDJ3FsPO3TA)

The first set of commands are for configuring seccomp and AppArmor profiles for your Docker host, and are only necessary if you have chosen to install BrowserBot. For more information on these requirements, see [Support for Page Load and Transaction Tests](#support-for-transaction-tests).

{% hint style="warning" %}
If the Docker host supports SELinux, you may have to disable it to run page load and transaction tests.
{% endhint %}

The second set of commands will install and set up the Enterprise Agent. Once these commands have been run, your Docker-based Enterprise Agent will be installed and start running. The Enterprise Agent will be restarted automatically upon Docker host restart.

{% hint style="info" %}
You may receive a **WARNING: Your kernel does not support swap limit capabilities, memory limited without swap** message when issuing the `docker run` command. You can safely continue, as this will not affect your Enterprise Agent installation.
{% endhint %}

The Enterprise Agent container will be automatically connected to the default **docker0** network bridge and assigned a private IP address. The container uses network address translation (NAT) to the Docker host default interface to connect the Enterprise Agent to the network. No additional network configuration is required.

## Stopping, Starting, and Restarting the Enterprise Agent

After installing the image, you can verify that the Enterprise Agent is running by using the `docker ps` command:

```
docker ps
```

Output should be similar to:

```
CONTAINER ID IMAGE                         COMMAND         CREATED        STATUS      PORTS NAMES
400b4ad7bb34 thousandeyes/enterprise-agent "/sbin/my_init" 2 minutes ago  Up 2 minutes      <agent-name>
```

You can stop the container by running the following command:

```
docker stop <agent-name>
```

**NOTE**: If you stop the container using the `docker stop` command, the container will not automatically restart upon Docker host restart.

To verify that the agent has been stopped, run `docker ps -a`. This shows the status of all containers, including stopped ones.

```
docker ps -a
```

Output should be similar to:

```
CONTAINER ID IMAGE                         COMMAND         CREATED        STATUS               NAMES
400b4ad7bb34 thousandeyes/enterprise-agent "/sbin/my_init" 2 minutes ago  Exited (0) 5 sec ago <agent-name>
```

You can start the agent container by using `docker start`:

```
docker start <agent-name>
```

**NOTE**: The Enterprise Agent container will automatically restart upon Docker host reboot if started with the `docker start` command.

## Removing an Enterprise Agent

To remove an Enterprise Agent container, use the `docker rm` command.

Note: use `-v` to remove anonymous Docker volumes that may be associated with the Enterprise Agent container.

```
docker rm -fv <agent-name>
```

If you're permanently removing an Enterprise Agent, delete the persistent volumes as well. If you're just updating the container, running `docker start` will automatically update the container to the latest version.

To remove the persistent volumes on your Docker host:

```
rm -Rf <host-os-agent-folder>/thousandeyes/<agent-name>
```

## Reinstalling the Enterprise Agent

You can easily remove and reinstall Enterprise Agent containers. You may need to reinstall the Enterprise Agent in a case of serious Enterprise Agent failure and/or when suggested to do so by ThousandEyes Support. All persistent data for the Enterprise Agent is stored in the persistent volumes on the host. As long as you keep the *agent-name* consistent, and persistent volumes on the host the same, the Enterprise Agent will keep its data and same identity in the ThousandEyes platform, even if you remove the container and replace it with a new one.

To reinstall the Enterprise Agent, do the following:

1. Ensure you have the latest Enterprise Agent image on your host by running the following command on the Docker host:

   `docker pull thousandeyes/enterprise-agent`
2. Log into ThousandEyes, and navigate to **Network & App Synthetics > Agent Settings**.
3. Click **+ Add New Agent** to open the form.
4. Click **Docker**\* for the **Package Type** setting.
5. Enter a name for your Enterprise Agent, which must be the same as the name of currently running Enterprise Agent you want to reinstall.
6. Enter a folder on the Docker host where persistent files for the existent Enterprise Agent are already stored (e.g. **/opt**).
7. (Optional) If your Docker agent will be running page load or transaction tests, do the following:
   1. On the **+Add New Agent** form, select **Install with BrowserBot support**.
   2. Copy the commands shown in the upper text box, and run them at the command line of your Docker host.

      These commands configure seccomp and AppArmor profiles for your Docker host. For information on these requirements, see [Support for Page Load and Transaction Tests](#support-for-transaction-tests).
   3. Additionally, if your Docker host supports SELinux, you may need to disable it in order to run page load or transaction tests.
8. Copy the commands generated for your container in the **+ Add New Agent** form, then paste and run them in the command line of your Docker host.

**Warning:** Removing data from persistent volumes on the host (*host-os-agent-folder*/thousandeyes/*agent-name*/*\**) will result in reinitialization of the agent. The agent will register as a new agent in ThousandEyes.

## Agent System Time

Docker containers use the host system kernel clock. Enterprise Agent containers cannot alter the clock. If an agent's system time is offset, you need to adjust host system time, ideally by configuring valid NTP servers on the host system.

## Advanced DNS Configuration

Enterprise Agent containers use the host's DNS settings by default. You can configure a different set of DNS servers for the Enterprise Agent, if needed. When using the `docker run` command upon Enterprise Agent installation, add the `--dns=<dns-server>` parameter before the last line. If you need to add multiple servers, repeat the command:

```
--dns=8.8.8.8 \
--dns=8.8.4.4 \
thousandeyes/enterprise-agent /sbin/my_init
```

## Exposing Ports for Agent-to-Agent Tests

If you are connecting your Docker-based Enterprise Agent to the world using the NAT network (which is Docker default), agent-to-agent tests targeting your Docker agent will not work out of the box. To enable the agent-to-agent test traffic to reach your Docker agent hosted behind a NAT network, relevant ports need to be exposed and published. To achieve this, add the following parameters to your `docker run` command:

```
--expose=49152/udp \
--expose=49153/udp \
--expose=49153/tcp \
--publish=49152:49152/udp \
--publish=49153:49153/udp \
--publish=49153:49153/tcp \
thousandeyes/enterprise-agent /sbin/my_init
```

## Agent Proxy Configuration

Customers deploying ThousandEyes Enterprise Agents behind a proxy may need proxy-specific configuration for the Enterprise Agent in order to use certain tests, report test data to the ThousandEyes collector, and perform software package updates.

You should configure proxy settings upon Enterprise Agent installation. See the *Deploying a Docker Agent* section of [Installing Enterprise Agents in Proxy Environments](https://docs.thousandeyes.com/product-documentation/enterprise-agents/installing-enterprise-agents-in-proxy-environments) for instructions on installing Docker.

You can verify the proxy settings of a running agent by running the following command on the Docker host:

```
docker exec <agent-name> cat /etc/te-agent.cfg | grep proxy
```

You cannot change the proxy configuration of a currently running agent. You must reinstall the agent with a new proxy configuration. See [Reinstalling the Enterprise Agent](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/docker-based-agent-installation#reinstalling-the-enterprise-agent).

## Support for Page Load and Transaction Tests

{% hint style="warning" %}
Prior to BrowserBot 2, the requirements outlined in this section applied only to agents running transaction tests.
{% endhint %}

The following should be considered during container deployment:

**seccomp**\
Security computing mode is a Linux kernel feature used to restrict container actions. The Docker community has documented [how seccomp is used with containers](https://docs.docker.com/engine/security/seccomp/). ThousandEyes provides a seccomp file that you can use to configure seccomp when deploying containers.

**AppArmor configuration**\
AppArmor is a mandatory access control (MAC) system used to limit an application's access to resources. AppArmor is currently the default MAC system for the Debian, Ubuntu, SuSE, and Arch Linux distributions.

**SELinux configuration**\
SELinux is a mandatory access control (MAC) system used to limit an application's access to resources. SELinux is currently the default MAC system for Red Hat Enterprise, CentOS, Fedora, Oracle, and Gentoo Linux distributions.

**user.max\_user\_namespaces** Distributions that share a common code base with Red Hat Enterprise Linux 7 may have a default **user.max\_user\_namespaces** value of 0, or may simply leave this feature disabled. The Docker community has documented [how this issue affects container deployment along with common resolutions](https://success.docker.com/article/user-namespace-runtime-error). In point release 7.6 and up, the **user.max\_user\_namespaces** value simply needs to be increased for proper operation. This feature is also required when [running a container as a user other than root](https://www.redhat.com/en/blog/preview-running-containers-without-root-rhel-76).

**snap** Note that Docker installed via Ubuntu's **snap** tool is not supported. Users should install Docker as suggested by the official Docker documentation at [docs.docker.com](https://docs.docker.com).

### Example Deployment (New Agent)

**Operating Systems Using seccomp or AppArmor**

ThousandEyes provides a Bash script to configure existing Docker environments to run transaction tests. If your Docker host relies on seccomp or AppArmor, do the following:

1. Download the script.

   ```
   curl -Os https://downloads.thousandeyes.com/bbot/configure_docker.sh
   ```
2. Make the script executable.

   ```
   chmod +x configure_docker.sh
   ```
3. Execute the script (requires **sudo** and **curl**).

   ```
   sudo ./configure_docker.sh
   ```

   The script creates a working directory, **/var/docker/configs**, and downloads some recommended configuration files for seccomp and AppArmor, if supported, on your Docker host.

   If AppArmor is installed on the Docker host, the script applies the given configuration using **apparmor\_parser**.

**Operating Systems Using SELinux**

Setting SELinux to "permissive" mode allows applications to run while logging any activity that would violate the system's current SELinux profile.

Before returning SELinux to "enforcing" mode, review the SELinux logs to see if your profile should be updated.

Next, deploy your agent using the the modified `run` command. For example:

```
 docker run \
    --hostname='<AGENT NAME>' \
    --memory=2g \
    --memory-swap=2g \
    --detach=true \
    --tty=true \
    --shm-size=512M \
    -e TEAGENT_ACCOUNT_TOKEN=<ACCOUNT TOKEN> \
    -e TEAGENT_INET=4 \
    -v '/var/docker/thousandeyes/<AGENT NAME>/te-agent':/var/lib/te-agent \
    -v '/var/docker/thousandeyes/<AGENT NAME>/te-browserbot':/var/lib/te-browserbot \
    -v '/var/docker/thousandeyes/<AGENT NAME>/log/':/var/log/agent \
    --cap-add=NET_ADMIN \
    --cap-add=SYS_ADMIN \
    --name '<AGENT NAME>' \
    --restart=unless-stopped \
    --security-opt seccomp=/var/docker/configs/te-seccomp.json \
    --security-opt apparmor=docker_sandbox \
    thousandeyes/enterprise-agent /sbin/my_init
```

## Troubleshooting and Log Information

If you're directed by ThousandEyes Customer Engineering team to pull log files for the agent, the logs are found in the persistent volume, under the **thousandeyes/*****agent-name*****/log** folder. The agent log file is called **te-agent.log**, and this file rolls over automatically. You can tail this log from the Docker host using the `tail -f` command. An example is found below, assuming **/opt** was the persistent storage location supplied, and **agent-name** is the name of the agent:

```
tail -f /opt/thousandeyes/agent-name/log/te-agent.log
```

## FAQ

**Question: How do I connect to the container shell for Docker agents?**

**Answer:** To access the container shell, run the following command on your container host, replacing `\<AGENT_CONTAINER_NAME\>` with the container name:

```
docker exec -it <AGENT_CONTAINER_NAME> bash -l
```

{% hint style="info" %}
The `-l` parameter ensures that Bash will utilize proxy settings configured for the agent.
{% endhint %}

To verify the agent is running, you can use the `sv status te-agent` command, which should return similar output to the example below:

```
# sv status te-agent
run: te-agent: (pid 653) 79389s
```

Additional commands include:

* Start the agent: `sv start te-agent`
* Restart the agent: `sv restart te-agent`
* Stop the agent: `sv stop te-agent`

For more information on configuration options and troubleshooting, see:

* [CLI Network Troubleshooting Utilities](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/troubleshooting/cli-network-troubleshooting-utilities)
* [Docker Agent Config Options](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/docker-agent-config-options)


# Linux Package Agent Installation

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

The ThousandEyes Enterprise Agent can be deployed on a variety of Linux distributions such as Ubuntu, Red Hat Enterprise Linux (RHEL), and CentOS. Supported operating systems can be found here: [Supported Enterprise Agent Operating Systems](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents#supported-enterprise-agent-operating-systems).

{% hint style="warning" %}
Customers who choose to install the ThousandEyes Enterprise Agent onto their own Linux system using the **Linux Package** installation method are responsible for system maintenance.
{% endhint %}

For Linux distributions not on this list, you may be able to install [Docker](https://www.docker.com/) and the Enterprise Agent Docker container. For more details, see [Enterprise Agent deployment using Docker](https://docs.thousandeyes.com/product-documentation/enterprise-agents/enterprise-agent-deployment-using-docker).

## Installation

{% hint style="warning" %}
The ThousandEyes for Government instance has additional requirements for Linux package installations. Refer to the [ThousandEyes for Government - FedRAMP® Moderate](https://docs.thousandeyes.com/product-documentation/thousandeyes-for-government#linux-package) documentation for prerequisites and configuration requirements **before** continuing.
{% endhint %}

Log in to the Linux system on which you will install the ThousandEyes Enterprise Agent. Log in either as the root user, or a user which has been granted “sudo” access to the necessary package management and other commands required for the installation. Then log into the ThousandEyes application and follow the steps found under **Network & App Synthetics > Agent Settings > Enterprise Agents > +Add New Agent > Linux Package**, explained in detail below.

The first step downloads the installation script from ThousandEyes:

```
curl -Os https://downloads.thousandeyes.com/agent/install_thousandeyes.sh
```

The second command enables execute permission for the installation script:

```
chmod +x install_thousandeyes.sh
```

The third command runs the script:

```
sudo ./install_thousandeyes.sh -b <Account Group Installation Token>
```

**Notes**

* The Account Group Installation Token identifies the Agent as belonging to a specific Account Group and can be found under **Network & App Synthetics > Agent Settings**. Click **+Add New Agent** and then **Show Account Group Token for Installation**.
* If there are multiple Account Groups in your organization you will need to copy the token from the Account Group context in which you wish the Agent to be first seen. An Agent can be shared between groups. Additional information could be found here: [Working with Agent settings](https://docs.thousandeyes.com/product-documentation/thousandeyes-basics/working-with-agent-settings).
* If multiple IP addresses are detected on the system, you will be prompted to choose the appropriate one during installation.

### Advanced Options

To display the advanced options when installing the Agent use either -h or --help flags.

```
$ ./install_thousandeyes.sh --help
Usage: ./install_thousandeyes.sh [-b [-L] [-W]] [-f] [-h] [-I INSTALL_LOG] [-l LOG_PATH] [-t PROXY_TYPE -P PROXY_LOCATION [-U PROXY_USER -u PROXY_PASS]] [-r REPO] [-s] [-v AGENT_VERSION] [-O] ACCOUNT_TOKEN
  -b                     Also install BrowserBot, an agent component that collects
                         Page Load and Transaction test data using an instance
                         of the Chromium browser
  -L                     Also install international language packages for BrowserBot (requires -b)
  -W                     Install BrowserBot without its recommended packages (e.g. te-xvfb) (requires -b)
  -f                     Force batch mode
  -h                     Print this message
  -I <INSTALL_LOG>       Set the install log location to INSTALL_LOG
  -l <LOG_PATH>          Set the log path to LOG_PATH
  -t <PROXY_TYPE>        Set the proxy type: DIRECT (default, no proxy), STATIC, or PAC
  -P <PROXY_LOCATION>    Set the proxy location, format depends on PROXY_TYPE
                           DIRECT
                             PROXY_LOCATION is an invalid option for DIRECT
                           STATIC
                             host:port for hostname or IPv4 address
                             [IPv6 IP]:port for IPv6 address
                           PAC
                             URL where PAC file can be found
  -U <PROXY_USER>        Set the proxy user to PROXY_USER
  -u <PROXY_PASS>        Set the proxy password to PROXY_PASS
  -a <PROXY_AUTH_TYPE>   Set the proxy authentication type: BASIC (default), NTLM
  -r <REPO>              Force the installer to install from REPO (overriding original ones)
  -s                     Skip the repository creation
  -v <AGENT_VERSION>     Specify agent version
  -O                     Install the agent, but do not start the agent services
```

## Post-Installation

Once the installation completes, the Agent will start automatically. Normally, within a minute the Agent will appear under **Network & App Synthetics > Agent Settings**.

![](/files/-M5xtP4y4Gw3qQhad3e8)

To avoid synchronization problems with the ThousandEyes collector it is strongly recommended that you install a Network Time Protocol (NTP) package. To download and install an NTP package issue the following commands on the Agents host machine:

#### Ubuntu

1. *sudo apt-get install ntp* (Download and install NTP service)
2. *service ntp start* (Start the NTP service)
3. *service ntp status* (View current status)

   If you wish to use alternate NTP servers, edit /etc/ntp.conf:

```
$ service ntp status
 * NTP server is running

$ cat /etc/ntp.conf
# /etc/ntp.conf, configuration for ntpd; see ntp.conf(5) for help

# Specify one or more NTP servers.

# Use servers from the NTP Pool Project. Approved by Ubuntu Technical Board
# on 2011-02-08 (LP: #104525). See http://www.pool.ntp.org/join.html for
# more information.
server 0.ubuntu.pool.ntp.org
server 1.ubuntu.pool.ntp.org
server 2.ubuntu.pool.ntp.org
server 3.ubuntu.pool.ntp.org
```

**Red Hat Enterprise Linux or CentOS**

1. *yum install ntp* (Install the NTP service)
2. systemctl start ntpd (Start the NTP service)
3. systemctl enable ntpd (Enable NTP to start on reboots)
4. systemctl status ntpd (Print the current status)

If you wish to use alternate NTP servers, edit /etc/ntp.conf:

```
$ systemctl status ntpd
● ntpd.service - Network Time Service
   Loaded: loaded (/usr/lib/systemd/system/ntpd.service; enabled; vendor preset: disabled)
   Active: active (running) since Wed 2017-03-01 16:23:16 EST; 15min ago
 Main PID: 12567 (ntpd)
   CGroup: /system.slice/ntpd.service
           └─12567 /usr/sbin/ntpd -u ntp:ntp -g

$ cat /etc/ntp.conf
# For more information about this file, see the man pages
# ntp.conf(5), ntp_acc(5), ntp_auth(5), ntp_clock(5), ntp_misc(5), ntp_mon(5).

# Use public servers from the pool.ntp.org project.
# Please consider joining the pool (http://www.pool.ntp.org/join.html).
server 0.centos.pool.ntp.org iburst
server 1.centos.pool.ntp.org iburst
server 2.centos.pool.ntp.org iburst
server 3.centos.pool.ntp.org iburst
```

We recommend you ensure the NTP service starts at boot time by restarting your system and verifying the ntpd process is automatically started.


# Raspberry Pi Agent Installation

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

You can run ThousandEyes Enterprise Agents on Raspberry Pi hardware. This approach can be advantageous if your organization has locations that do not have hardware to host the agent, or that do not have technical staff to set up the agent.

With the Raspberry Pi, you can obtain low-cost hardware; configure it and the agent on it; then ship it to another location.

## System Requirements

* Raspberry Pi 4 Model B (4GB or 8GB model)

{% hint style="info" %}
ThousandEyes recommends that you obtain a Raspberry Pi bundle, such as from [CanaKit](https://www.canakit.com/) or [Vilros](https://vilros.com/), to ensure that all the parts you'll need are included in a single order.
{% endhint %}

{% hint style="warning" %}
ThousandEyes does not support Raspberry Pi 4 Model B (2GB).
{% endhint %}

* One of the following models of microSD card:
  * Samsung EVO Plus (32GB minimum required)
  * SanDisk Extreme (32 GB minimum required)
* Power over Ethernet (PoE) adapter or a standard USB-C power supply

**NOTE: A heat sink is not required.**

## Installation

1. Download the latest image in **Network & App Synthetics > Agent Settings > Enterprise Agents > Add New Enterprise Agent**.
2. Install your favorite image writer.

   For example, [Etcher](https://www.balena.io/etcher/) works for both macOS and Windows.
3. Using the USB adapter that comes with your Raspberry Pi kit, write the image to your microSD card.

   ![](/files/-M8rzRQAFlcr8hBosENU)
4. Select the drive of your Rasperry Pi device.

   The drive should be displayed as a 32 GB Mass Storage Device.

   NOTE: If the size displayed is smaller, this is likely because your kit's device is shipped with a small test partition.
5. Click **Flash**.

   You don't need to uncompress the image file.

   \[macOS only] Enter your password to authorize this action.

   **NOTE: The flashing process takes a few minutes.**
6. Eject/remove the microSD.

   Doing so limits the possibility of corrupting the image.
7. Go to the IP address of the Raspberry Pi:

   * If your computer is on the same LAN as the Raspberry Pi, open a browser tab and go to <https://tepi.local>.
   * Otherwise, connect the Raspberry Pi to a screen; open a console window and find the device's IP address. Then, on your computer, open a browser tab and go to that IP. For an example, see [ThousandEyes Physical Appliance (TEPA) Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-physical-appliance-installation#configuring-the-enterprise-agent).

   The physical appliance setup wizard opens.
8. On <https://tepi.local>, log in with the username **admin** and password **welcome**.

   ![](/files/-M8rzRQHmt7rn7mrpVAG)
9. In the physical appliance setup wizard, on the **Appliance Access** screen, set a new password.

   On this page, you can also add your SSH key. You can also set up your SSH key [using this method](https://docs.thousandeyes.com/product-documentation/enterprise-agents/connecting-to-the-thousandeyes-virtual-appliance-using-ssh-mac-linux).
10. On the **Agent** screen, add your account group token.

    You can find the account group token in the ThousandEyes application at **Network & App Synthetics > Agent Settings > Enterprise Agents> Add New Enterprise Agent**.

    **NOTE: The ThousandEyes component BrowserBot is not supported for Raspberry Pi implementations. This means that the Enterprise Agent on Raspberry Pi cannot run page load tests and transaction tests.**
11. Click **Continue**.

    When installation and configuration are complete, the **Review** screen shows appliance status and diagnostics.
12. Follow up.

* You should now see your Raspberry Pi listed in the ThousandEyes application at **Network & App Synthetics > Agent Settings > Enterprise Agents**.
* The default name for the agent on your Raspberry Pi is **tepi** (ThousandEyes Pi). You can rename the agent in the agents list by selecting it and editing its name in the details panel that is displayed.
* You can check on your new agent's activities on the [**Agent Statistics** tab](https://docs.thousandeyes.com/product-documentation/enterprise-agents/enterprise-agent-utilization#utilization-in-the-thousandeyes-application).


# Appliances


# Enterprise Agent Deployment Using ThousandEyes Virtual Appliance (Hyper-V)

Check out the screencast below for instructions on deploying the ThousandEyes virtual appliance using the Microsoft Hyper-V platform for Windows Server 2012 or Windows Server 2012 R2.

[![Enterprise Agent Deployment Using Hyper-V](https://embed-fastly.wistia.com/deliveries/88d7282a22f33b17944de1a2b5efb9b988854d79.jpg?image_play_button_size=2x\&image_crop_resized=960x540\&image_play_button=1\&image_play_button_color=f65c11e0)](https://fast.wistia.net/embed/iframe/7i0q5osoqc)

For a list of supported Windows Server versions, and for instructions on installing on other Windows Server versions, see [ThousandEyes Virtual Appliance Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-virtual-appliance-installation).


# Enterprise Agent Deployment Using ThousandEyes Virtual Appliance (OVA)

Check out the screencast below for instructions on deploying the ThousandEyes virtual appliance using the OVA template format, and VirtualBox as the hypervisor platform.

[![Enterprise Agent Deployment Using OVA](https://embed-fastly.wistia.com/deliveries/5cac2db838075b538729a80ddb8c0c0e82c7ba70.jpg?image_play_button_size=2x\&image_crop_resized=960x540\&image_play_button=1\&image_play_button_color=f65c11e0)](https://fast.wistia.net/embed/iframe/ymule3tgmo)


# Cisco Devices

ThousandEyes provides customers with a 360-degree view of their digital ecosystem. Customers can install and configure ThousandEyes Enterprise Agent vantage points on Cisco switches and routers to access this real-time map of how their customers and employees experience critical services.

This article provides an overview of terminology, the supported Cisco devices with links to the available installation methods, and next steps for using ThousandEyes.

## Supported Devices

Once you have activated your account, review the support matrixes for each supported device type listed below to identify the devices you wish to install Enterprise Agents on, the system requirements (hardware/software etc), and the available installation methods. For additional reference, see the [Cisco SD-WAN Systems and Interfaces Configuration Guide](https://www.cisco.com/c/en/us/td/docs/routers/sdwan/configuration/system-interface/ios-xe-17/systems-interfaces-book-xe-sdwan/sdwan-thousandeyes.html).

{% hint style="info" %}
Cisco app-hosting is based on Docker containers. As a part of container package best practices, we recommend updating your container regularly.
{% endhint %}

* For Cisco Catalyst switches, see [Catalyst Switches](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/catalyst-switches).
* For Cisco Catalyst routers, see [Catalyst Routers](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/catalyst-routers).
* For Cisco Nexus switches, see [Nexus Switches](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/nexus-switches).
* For Aggregated Services Routers (ASR) and Integrated Services Routers (ISR), see [Service Routers](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/service-routing).
* For Industrial Ethernet switches, see [Industrial Ethernet Switches](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/industrial-ethernet-switches).
* For Industrial routers, see [Industrial Routers](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/industrial-routers).
* For Meraki appliances, see [Meraki MX Appliances](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/meraki).
* For Cisco Enterprise NFV Infrastructure Software (NFVIS), see [Cisco Enterprise NFV Infrastructure Software](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/nfvis).

## Next Steps

Once your Enterprise Agent vantage points have been installed, you can start to build out the tests, alerts, dashboards, and reports, that will allow you to monitor your entire environment. The articles below provide information on where to get started, and your next steps.

* [Getting Started with Views](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-views)
* [Getting Started with Tests](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-tests)
* [How Alerts Work](https://docs.thousandeyes.com/product-documentation/alerts)
* [Working with the Dashboard](https://docs.thousandeyes.com/product-documentation/thousandeyes-basics/working-with-the-dashboard)


# Catalyst Switches

ThousandEyes supports installing Enterprise Agents on Cisco Catalyst switches using either Cisco application hosting or the Cisco Catalyst Center. This reference article provides a brief overview of Cisco application hosting, licensing information, system requirements for each supported Cisco Catalyst switch, as well as links to supported installation methods.

Please review the tables below before beginning the installation and setup process.

## Application Hosting Overview

To support application hosting capabilities on Cisco Catalyst switches, the switch provides hardware resources where applications can reside and execute. Cisco IOS XE reserves dedicated memory and CPU resources for application hosting to provide a separate execution space for user applications, without compromising the integrity and performance of the switch.

For more information on Cisco application hosting, see [Application Hosting](https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/1718/b-1718-programmability-cg/m_1718_prog_thousandeyes.html).

## Licensing and Entitlements

A Cisco Switching Advantage license is required for each Enterprise Agent installed on a Cisco Catalyst 9k series switch. Customers are entitled to 22 units per eligible DNA license. For more information, see [About Units](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/about-usage-units).

{% hint style="warning" %}
Use rights for the ThousandEyes entitlement in Cisco DNA Advantage with Catalyst 9300 and 9400 switches do not apply in the ThousandEyes government instance.
{% endhint %}

## Supported Devices and System Requirements

### Catalyst 9300 Series

{% hint style="info" %}
All Cisco Catalyst 9300 series switches are supported. Individual models will be added to the table below if the system requirements differ from previously documented models.
{% endhint %}

| Platform       | Architecture | Requirements                                                                                                                | Additional                                                                                                                                                                                                              |
| -------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Catalyst 9300  | x86\_64      | <ul><li>Operating System: IOS XE 17.3.3 or later.</li><li>Orchestrator: Cisco Catalyst Center 2.2.2.3 or later.</li></ul>   | <ul><li><strong>Supported Modules</strong>: BrowserBot (IOS XE 17.6.1 or later, <a href="https://www.cisco.com/c/en/us/td/docs/switches/lan/catalyst9300/hardware/install/b_c9300_hig.html">SSD Required</a>)</li></ul> |
| Catalyst 9300L | x86\_64      | <ul><li>Operating System: IOS XE 17.6.1 or later.</li><li>Orchestrator: Cisco Catalyst Center 2.2.2.3 or later.</li></ul>   | <ul><li><strong>Supported Modules</strong>: BrowserBot (<a href="https://www.cisco.com/c/en/us/td/docs/switches/lan/catalyst9300/hardware/install/b_c9300_hig.html">SSD Required</a>)</li></ul>                         |
| Catalyst 9350  | x86\_64      | <ul><li>Operating System: IOS XE 17.18.1 or later.</li><li>Orchestrator: Cisco Catalyst Center 2.3.7.10 or later.</li></ul> | <ul><li><strong>Supported Modules</strong>: BrowserBot (<a href="https://www.cisco.com/c/en/us/td/docs/switches/lan/catalyst9300/hardware/install/b_c9300_hig.html">SSD Required</a>)</li></ul>                         |
| Catalyst 9300X | x86\_64      | <ul><li>Operating System: IOS XE 17.3 or later.</li><li>Orchestrator: Cisco Catalyst Center 2.2.2.3 or later.</li></ul>     | <ul><li><strong>Supported Modules</strong>: BrowserBot (minimum IOS XE 17.6.1, <a href="https://www.cisco.com/c/en/us/td/docs/switches/lan/catalyst9300/hardware/install/b_c9300_hig.html">SSD Required</a>)</li></ul>  |

### Catalyst 9400 Series

| Platform       | Architecture | Requirements                                                                                                               | Additional                                                                                                                                                                                                             |
| -------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Catalyst 9400  | x86\_64      | <ul><li>Operating System: IOS XE 17.5.1 or later.</li><li>Orchestrator: Cisco Catalyst Center 2.2.2.3 or later.</li></ul>  | <ul><li><strong>Supported Modules</strong>: BrowserBot (minimum IOS XE 17.6.1, <a href="https://www.cisco.com/c/en/us/td/docs/switches/lan/catalyst9400/hardware/install/b_c9400_hig.html">SSD Required</a>)</li></ul> |
| Catalyst 9400X | x86\_64      | <ul><li>Operating System: IOS XE 17.18.1 or later.</li><li>Orchestrator: Cisco Catalyst Center 2.2.2.3 or later.</li></ul> | <ul><li><strong>Supported Modules</strong>: BrowserBot (<a href="https://www.cisco.com/c/en/us/td/docs/switches/lan/catalyst9400/hardware/install/b_c9400_hig.html">SSD Required</a>)</li></ul>                        |

{% hint style="info" %}
Cisco Catalyst 9410 switches require additional setup steps to enable the AppGigabitEthernet port. For more information on the required steps, see the “Application Hosting on Cisco Catalyst 9410 Series Switches” section of Cisco's [Programmability Configuration Guide](https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/176/b_176_programmability_cg/m_176_prog_app_hosting.html#Cisco_Concept.dita_f7ac8f15-7a54-45d6-bae8-088b3bd2e6c0).
{% endhint %}

## Supported Installation Methods

* [Install Enterprise Agents on Cisco Switches with Application Hosting](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/installing-enterprise-agents-on-cisco-switches-with-docker)


# Catalyst Routers

ThousandEyes supports installing Enterprise Agents on Cisco Catalyst routers using either Cisco application hosting or the Cisco Catalyst SD-WAN Manager. This reference article provides a brief overview of application hosting and the SD-WAN manager, system requirements for each supported Cisco Catalyst router, as well as links to supported installation methods.

Please review the tables below before beginning the installation and setup process.

## Application Hosting Overview

To support application hosting capabilities on Cisco Catalyst routers, the router provides hardware resources where applications can reside and execute. Cisco IOS XE reserves dedicated memory and CPU resources for application hosting to provide a separate execution space for user applications, without compromising the integrity and performance of the router.

{% hint style="info" %}
ThousandEyes supports both SD-WAN and IOS XE modes for Cisco Application Hosting deployments.
{% endhint %}

For more information on Cisco application hosting, see [Application Hosting](https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/1718/b-1718-programmability-cg/m_1718_prog_thousandeyes.html).

## SD-WAN Manager

ThousandEyes supports installing Enterprise Agents on Cisco Catalyst routers running in SD-WAN mode that are managed by SD-WAN Manager. For more information about SD-WAN Manager, see the [SD-WAN Manager Documentation](https://www.cisco.com/c/en/us/solutions/enterprise-networks/sd-wan/vmanage.html).

{% hint style="info" %}
vEdge routers must be added to the SD-WAN Manager inventory list before installation. For more information, see the [SD-WAN Manager Documentation](https://www.cisco.com/c/en/us/solutions/enterprise-networks/sd-wan/vmanage.html).
{% endhint %}

## Supported Devices and System Requirements

### Catalyst 8100 Series Routers

| Platform      | Architecture | Requirements                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Additional                                                |
| ------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Catalyst 8151 | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.18.1 or later.</li><li><strong>Hardware Requirements</strong>: No additional hardware required (16GB M.2 SSD drive is included by default).</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.18 and later.</li><li><strong>ThousandEyes Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.18 and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| Catalyst 8161 | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.18.1 or later.</li><li><strong>Hardware Requirements</strong>: No additional hardware required (16GB M.2 SSD drive is included by default).</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.18 and later.</li><li><strong>ThousandEyes Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.18 and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |

### Catalyst 8200 Series Routers

| Platform       | Architecture | Requirements                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Additional                                                |
| -------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Catalyst 8200  | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.6.1 or later.</li><li><strong>Hardware Requirements</strong>: No additional hardware required (16GB M.2 SSD drive is included by default).</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.6 and later.</li><li><strong>ThousandEyes Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.16 and later.</li></ul>   | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| Catalyst 8200L | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.6.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.6 and later.</li><li><strong>ThousandEyes Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.16 and later.</li></ul>                                                | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| Catalyst 8231  | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.18.1 or later.</li><li><strong>Hardware Requirements</strong>: No additional hardware required (16GB M.2 SSD drive is included by default).</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.18 and later.</li><li><strong>ThousandEyes Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.18 and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| Catalyst 8235  | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.18.1 or later.</li><li><strong>Hardware Requirements</strong>: No additional hardware required (16GB M.2 SSD drive is included by default).</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.18 and later.</li><li><strong>ThousandEyes Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.18 and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |

### Catalyst 8300 Series Routers

| Platform      | Architecture | Requirements                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Additional                                                |
| ------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Catalyst 8300 | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.6.1 or later.</li><li><strong>Hardware Requirements</strong>: No additional hardware required (16GB M.2 SSD drive is included by default).</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.6 and later.</li><li><strong>ThousandEyes Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.16 and later.</li></ul>   | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| Catalyst 8355 | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.18.1 or later.</li><li><strong>Hardware Requirements</strong>: No additional hardware required (16GB M.2 SSD drive is included by default).</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.18 and later.</li><li><strong>ThousandEyes Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.18 and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| Catalyst 8375 | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.15.3 or later (not supported in 17.16).</li><li><strong>Hardware Requirements</strong>: No additional hardware required (16GB M.2 SSD drive is included by default).</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.15.3 and later (not supported in 20.16).</li></ul>                                                                                                | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |

### Catalyst 8400 Series Routers

| Platform      | Architecture | Requirements                                                                                                                                                                                                                                                                                                                                                                                                 | Additional                                                |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| Catalyst 8455 | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.15.3 or later (not supported in 17.16).</li><li><strong>Hardware Requirements</strong>: No additional hardware required (16GB M.2 SSD drive is included by default).</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.15.3 and later (not supported in 20.16).</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| Catalyst 8475 | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.15.3 or later (not supported in 17.16).</li><li><strong>Hardware Requirements</strong>: No additional hardware required (16GB M.2 SSD drive is included by default).</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.15.3 and later (not supported in 20.16).</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |

### Catalyst 8500 Series Routers

| Platform       | Architecture | Requirements                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Additional                                                |
| -------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| Catalyst 8500  | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.8.1 and later.</li><li><strong>Hardware Requirements</strong>: No additional hardware required (16GB M.2 SSD drive is included by default).</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.8.1 and later.</li><li><strong>ThousandEyes Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.16 and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| Catalyst 8500L | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.8.1 and later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.8.1 and later.</li><li><strong>ThousandEyes Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.16 and later.</li></ul>                                              | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| Catalyst 8550  | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.15.3 or later (not supported in 17.16).</li><li><strong>Hardware Requirements</strong>: No additional hardware required (16GB M.2 SSD drive is included by default).</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.15.3 and later (not supported in 20.16).</li></ul>                                                                                                 | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| Catalyst 8570  | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.15.3 or later (not supported in 17.16).</li><li><strong>Hardware Requirements</strong>: No additional hardware required (16GB M.2 SSD drive is included by default).</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager (previously vManage) 20.15.3 and later (not supported in 20.16).</li></ul>                                                                                                 | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |

## Supported Installation Methods

* [Install Enterprise Agents on Cisco Routers with Application Hosting](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/installing-enterprise-agents-on-cisco-routers-with-application-hosting)
* [Install Enterprise Agents on Cisco Routers with SD-WAN Manager Feature Templates](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/installation-methods/installing-enterprise-agents-on-cisco-routers-using-sd-wan-manager-feature-templates)
* [Install Enterprise Agents on Cisco Routers with SD-WAN Manager ThousandEyes Workflow](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/installation-methods/installing-enterprise-agents-on-cisco-routers-using-sd-wan-manager-thousandeyes-workflow)


# Nexus Switches

ThousandEyes supports installing Enterprise Agents on Cisco Nexus switches running NX-OS using Cisco application hosting. This reference article provides a brief overview application hosting, entitlements, system requirements for each supported Cisco Nexus switch, and links to supported installation methods.

Please review the tables below before beginning the installation and setup process.

## Application Hosting Overview

To support application hosting capabilities on Cisco Nexus switches, the switch provides hardware resources where applications can reside and execute. Cisco IOS XE reserves dedicated memory and CPU resources for application hosting to provide a separate execution space for user applications, without compromising the integrity and performance of the switch.

For more information on Cisco application hosting, see [Application Hosting](https://www.cisco.com/c/en/us/td/docs/dcn/nx-os/nexus9000/105x/programmability/cisco-nexus-9000-series-nx-os-programmability-guide-105x/m-application-hosting.html).

## Licensing and Entitlements

ThousandEyes licenses for Cisco Nexus devices are not included alongside the purchase of a Cisco Switching Advantage license. They are only available for purchase directly from the Cisco Global Price List (GPL). These licenses can be purchased in addition to the embedded entitlements in order to gain access to the use of Cloud Agent and Endpoint Agent vantage points, Internet Insights, and to expand your use of ThousandEyes.

## Supported Devices and System Requirements

### Nexus 9300 Series Switches

| Platform       | Architecture | Requirements                                                                      | Additional                                                                                                                                                                                                            |
| -------------- | ------------ | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nexus 9300-FX  | x86\_64      | <ul><li><strong>Application Hosting</strong>: NX-OS 10.3(3)F and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li><li><a href="https://www.cisco.com/c/en/us/products/collateral/switches/nexus-9000-series-switches/datasheet-c78-742284.html">Datasheet</a></li></ul>             |
| Nexus 9300-FX2 | x86\_64      | <ul><li><strong>Application Hosting</strong>: NX-OS 10.3(3)F and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li><li><a href="https://www.cisco.com/c/en/us/products/collateral/switches/nexus-9000-series-switches/datasheet-c78-742282.html">Datasheet</a></li></ul>             |
| Nexus 9300-FX3 | x86\_64      | <ul><li><strong>Application Hosting</strong>: NX-OS 10.3(3)F and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li><li><a href="https://www.cisco.com/c/en/us/products/collateral/switches/nexus-9000-series-switches/datasheet-c78-744052.html">Datasheet</a></li></ul>             |
| Nexus 9300-GX  | x86\_64      | <ul><li><strong>Application Hosting</strong>: NX-OS 10.3(3)F and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li><li><a href="https://www.cisco.com/c/en/us/products/collateral/switches/nexus-9000-series-switches/nexus-9300-gx-series-switches-ds.html">Datasheet</a></li></ul> |
| Nexus 9300-GX2 | x86\_64      | <ul><li><strong>Application Hosting</strong>: NX-OS 10.3(3)F and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li><li><a href="https://www.cisco.com/c/en/us/products/collateral/switches/nexus-9000-series-switches/datasheet-c78-743854.html">Datasheet</a></li></ul>             |

### Nexus 9400 Series Switches

| Platform   | Architecture | Requirements                                                                      | Additional                                                                                                                                                                                                                          |
| ---------- | ------------ | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nexus 9400 | x86\_64      | <ul><li><strong>Application Hosting</strong>: NX-OS 10.3(3)F and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li><li><a href="https://www.cisco.com/c/en/us/products/collateral/switches/nexus-9000-series-switches/nexus9400-series-switches-ds.html?dtid=osscdc000283">Datasheet</a></li></ul> |

### Nexus 9500 CloudScale Series Switches

| Platform                                                                             | Architecture | Requirements                                                                      | Additional                                                                                                                                                                                                                                                                          |
| ------------------------------------------------------------------------------------ | ------------ | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <ul><li>Nexus 9504-FM-E2</li><li>Nexus 9508-FM-E2</li><li>Nexus 9516-FM-E2</li></ul> | x86\_64      | <ul><li><strong>Application Hosting</strong>: NX-OS 10.3(3)F and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li><li>Modular switches use the SUP resources for hosting applications.</li><li><a href="https://www.cisco.com/c/en/us/products/collateral/switches/nexus-9000-series-switches/datasheet-c78-729404.html">Datasheet</a>.</li></ul> |
| <ul><li>Nexus 9504-FM-G</li><li>Nexus 9508-FM-G</li><li>Nexus 9516-FM-G</li></ul>    | x86\_64      | <ul><li><strong>Application Hosting</strong>: NX-OS 10.3(3)F and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li><li>Modular switches use the SUP resources for hosting applications.</li><li><a href="https://www.cisco.com/c/en/us/products/collateral/switches/nexus-9000-series-switches/datasheet-c78-729404.html">Datasheet</a>.</li></ul> |

### Nexus 9500 R-Series Switches

| Platform                                                                                                                                                                                                                                | Architecture | Requirements                                                                      | Additional                                                                                                                                                                                                                                                                          |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <ul><li>Nexus 9504-FM-R</li><li>Nexus 9504-FM-RX</li><li>Nexus 9504-FM-R2</li><li>Nexus 9508-FM-R</li><li>Nexus 9508-FM-RX</li><li>Nexus 9508-FM-R2</li><li>Nexus 9516-FM-R</li><li>Nexus 9516-FM-RX</li><li>Nexus 9516-FM-E2</li></ul> | x86\_64      | <ul><li><strong>Application Hosting</strong>: NX-OS 10.3(3)F and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li><li>Modular switches use the SUP resources for hosting applications.</li><li><a href="https://www.cisco.com/c/en/us/products/collateral/switches/nexus-9000-series-switches/datasheet-c78-738321.html">Datasheet</a>.</li></ul> |

### Nexus 9800 Series Switches

| Platform                     | Architecture | Requirements                                                                      | Additional                                                                                                                                                                                                                                                 |
| ---------------------------- | ------------ | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <ul><li>Nexus 9808</li></ul> | x86\_64      | <ul><li><strong>Application Hosting</strong>: NX-OS 10.3(3)F and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li><li><a href="https://www.cisco.com/c/en/us/products/collateral/switches/nexus-9000-series-switches/nexus9800-series-switches-ds.html?dtid=osscdc000283#Productspecifications">Datasheet</a>.</li></ul> |

## Supported Installation Methods

* [Install Enterprise Agents on Nexus Switches with Application Hosting](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/installation-methods/installing-enterprise-agents-on-cisco-nexus-switches-with-application-hosting)


# Service Routers

ThousandEyes supports installing Enterprise Agents on Cisco Aggregation Services routers (ASR) and Integrated Services routers (ISR) using the command line interface (CLI) or the SD-WAN Manager.

This reference article provides a brief overview of the CLI and the SD-WAN manager, system requirements for each supported Cisco ASR and ISR device, as well as links to supported installation methods.

Please review the tables below before beginning the installation and setup process.

## SD-WAN Manager

ThousandEyes supports installing Enterprise Agents on Cisco Catalyst routers running in SD-WAN mode that are managed by SD-WAN Manager. For more information about SD-WAN Manager, see the [SD-WAN Manager Documentation](https://www.cisco.com/c/en/us/solutions/enterprise-networks/sd-wan/vmanage.html).

{% hint style="info" %}
vEdge routers must be added to the SD-WAN Manager inventory list before installation. For more information, see the [SD-WAN Manager Documentation](https://www.cisco.com/c/en/us/solutions/enterprise-networks/sd-wan/vmanage.html).
{% endhint %}

## Supported Devices and System Requirements

### Aggregated Service Routers

| Platform         | Architecture | Requirements                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Additional                                                |
| ---------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| ASR 1000         | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 16.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires an SSD.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                             | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ASR 1001-X       | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.8.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.8.1 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>                                                                                                                      | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ASR 1001-HX      | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.8.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM. <strong>Note</strong>: All 1001-HX devices come by default with 32GB of bootflash built-in. Additional bootflash is not required.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.8.1 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>  | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ASR 1002-X       | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.8.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.8.1 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>                                                                                                                      | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ASR 1002-HX      | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.8.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 16GB RAM. <strong>Note</strong>: All 1002-HX devices come by default with 32GB of bootflash built-in. Additional bootflash is not required.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.8.1 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ASR 1006 (RP2)   | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.8.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM, 8GB Flash, and 80GB HDD.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.8.1 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>                                                                                                           | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ASR 1006-X (RP3) | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.8.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash (includes 100GB SSD by default).</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.8.1 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>                                                                                      | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ASR 1009-X (RP3) | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.8.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash (includes 100GB SSD by default).</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.8.1 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>                                                                                      | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |

### Integrated Service Routers

| Platform     | Architecture | Requirements                                                                                                                                                                                                                                                                                                                                                                                                        | Additional                                                |
| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| ISR 1100X-6G | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.7 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 16GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.7.1 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>   | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ISR 1111X    | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.16.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>  | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ISR 1121X    | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.16.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>  | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ISR 1126X    | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.16.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>  | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ISR 1127X    | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.16.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>  | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ISR 1131X    | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.16.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 16GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ISR 1161X    | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.16.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>  | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ISR 4221X    | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.6.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.6 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>    | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ISR 4321     | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.6.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.6 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>    | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ISR 4331     | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.6.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.6 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>    | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ISR 4351     | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.6.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.6 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>    | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ISR 4400     | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.6.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.6 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>    | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ISR 4431     | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.6.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.6 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>    | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ISR 4451     | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.6.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.6 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>    | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| ISR 4461     | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.6.1 or later.</li><li><strong>Hardware Requirements</strong>: Requires 8GB RAM and 8GB Flash.</li><li><strong>Feature Template Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.6 and later.</li><li><strong>Simplified Workflow Management Requirements (SD-WAN Manager Only)</strong>: SD-WAN Manager 20.16 and later.</li></ul>    | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |

## Supported Installation Methods

* [Install Enterprise Agents on Cisco Routers with Application Hosting](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/installation-methods/installing-enterprise-agents-on-cisco-routers-with-application-hosting)
* [Install Enterprise Agents on Cisco Routers with SD-WAN Manager Feature Templates](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/installation-methods/installing-enterprise-agents-on-cisco-routers-using-sd-wan-manager-feature-templates)
* [Install Enterprise Agents on Cisco Routers with SD-WAN Manager Simplified Workflow](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/installation-methods/installing-enterprise-agents-on-cisco-routers-using-sd-wan-manager-thousandeyes-workflow)


# Industrial Ethernet Switches

ThousandEyes supports installing Enterprise Agents on Cisco Industrial Ethernet switches using Cisco application hosting. This reference article provides a brief overview of Cisco application hosting, system requirements for each supported Cisco Industrial Edge switch, as well as links to supported installation methods.

Please review the tables below before beginning the installation and setup process.

## Application Hosting Overview

To support application hosting capabilities on Cisco Industrial Edge switches, the switch provides hardware resources where applications can reside and execute. Cisco IOS XE reserves dedicated memory and CPU resources for application hosting to provide a separate execution space for user applications, without compromising the integrity and performance of the switch.

For more information on Cisco application hosting, see [Application Hosting](https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/1718/b-1718-programmability-cg/m_1718_prog_thousandeyes.html).

## Licensing and Entitlements

A Network Advantage license is required for each installed Industrial Ethernet Switch.

## Supported Devices and System Requirements

| Platform | Architecture | Requirements                                                                                                                               | Additional                                                |
| -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| IE3500   | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.18.1 or later.</li><li><strong>License</strong>: Cisco Switching Advantage.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| IE9310   | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.18.1 or later.</li><li><strong>License</strong>: Cisco Switching Advantage.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| IE9320   | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.18.1 or later.</li><li><strong>License</strong>: Cisco Switching Advantage.</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |

## Supported Installation Methods

* [Installing Enterprise Agents on Cisco Switches with Application Hosting](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/installing-enterprise-agents-on-cisco-switches-with-docker)


# Industrial Routers

ThousandEyes supports installing Enterprise Agents on Cisco Industrial routers using Cisco application hosting. This reference article provides a brief overview of Cisco application hosting, system requirements for each supported Cisco Industrial router, as well as a link to the supported installation method.

Please review the tables below before beginning the installation and setup process.

## Application Hosting Overview

To support application hosting capabilities on Cisco Industrial routers, the router provides hardware resources where applications can reside and execute. Cisco IOS XE reserves dedicated memory and CPU resources for application hosting to provide a separate execution space for user applications, without compromising the integrity and performance of the switch.

For more information on Cisco application hosting, see [Application Hosting](https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/1718/b-1718-programmability-cg/m_1718_prog_thousandeyes.html).

## Supported Devices and System Requirements

| Platform  | Architecture | Requirements                                                                                                                            | Additional                                                |
| --------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| IR1101    | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.18.1 or later.</li></ul>                                                           | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| IR1833-K9 | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.18.1 or later.</li></ul>                                                           | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| IR1835-K9 | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.18.1 or later.</li></ul>                                                           | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| IR8140H   | aarch64      | <ul><li><strong>Operating System</strong>: IOS XE 17.18.1 or later.</li><li><strong>Hardware Requirements</strong>: 100GB SSD</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |
| IR8340-K9 | x86\_64      | <ul><li><strong>Operating System</strong>: IOS XE 17.18.1 or later.</li><li><strong>Hardware Requirements</strong>: 100GB SSD</li></ul> | <ul><li><strong>Supported Modules</strong>: N/A</li></ul> |

## Supported Installation Methods

* [Installing Enterprise Agents on Cisco Routers with Application Hosting](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/installation-methods/installing-enterprise-agents-on-cisco-routers-with-application-hosting)


# Meraki MX Appliances

The ThousandEyes - Meraki integration allows users to install ThousandEyes Enterprise Agents on supported Meraki devices, providing better monitoring and testing capabilities for customers interested in improving the quality of their experience and adding the appropriate SD-WAN policies to optimize network performance.

This article provides an overview for the integration and the supported devices.

## Use Cases

Meraki Insights (MI) is designed to give Meraki customers an easy way to monitor the performance of web applications and WAN Links on their network and easily identify if any issues are likely being caused by the network (LAN or WAN) or the application server. The data used by MI is based on end-user HTTP/S data that’s already traversing the MX appliance and does not need synthetic probing.

With the ThousandEyes integration, customers can now benefit from enhanced visibility and alerting capabilities by creating customized network and application testing for critical applications inside or outside their infrastructure. For example, a customer can now monitor their internal DNS server response time and availability, as well as measure the average resolution time for a specific domain.

## Definitions

* **Tenant**: The target domain in the test template.

## Supported Devices and System Requirements

| Meraki Device                                                                                                                                                                 | Supported Test Types                                                                                                                                                                | Firmware Requirements | Mode                                                                                 |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------ |
| <ul><li>MX67</li><li>MX67W</li><li>MX67C</li><li>MX68</li><li>MX68W</li><li>MX68CW</li><li>MX75</li><li>MX85</li><li>MX95</li><li>MX105</li><li>MX250</li><li>MX450</li></ul> | All non-browser tests (see [Limitations](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/meraki#limitations)). | MX 18.104 or higher.  | NAT Mode is required. Meraki devices running in Concentrator mode are not supported. |
| <ul><li>C8111-G2-MX</li><li>C8111-C-G2-MX</li><li>C8121-G2-MX</li><li>C8121-W-G2-MX</li><li>C8121-CW-G2-MX</li><li>C8455-G2-MX</li></ul>                                      | All non-browser tests (see [Limitations](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/meraki#limitations)). | MX 26.1 or higher.    | NAT Mode is required. Meraki devices running in Concentrator mode are not supported. |

## Licensing

### Meraki Licensing

To take advantage of the ThousandEyes - Meraki integration, you will need:

* The SD-WAN+ license (for agent installation and test deployment), or
* The Advanced Security license (for agent installation only)

For more information on Meraki licenses, see [Meraki MX Security and SD-WAN Licensing](https://documentation.meraki.com/General_Administration/Licensing/Meraki_MX_Security_and_SD-WAN_Licensing).

### ThousandEyes Licensing

The Meraki device will have access to the available units in the ThousandEyes account. See the [ThousandEyes Product Description](https://www.cisco.com/c/dam/en_us/about/doing_business/legal/OfferDescriptions/ThousandEyes-Cloud-Service-Product-Description.pdf) for the terms and conditions applicable to the use of the ThousandEyes platform.

Meraki SDWAN+ customers can claim up to 50 free tests based on their licensing level and supported device count. For more information on how the licenses are calculated, please refer to the [Meraki MX ThousandEyes Configuration Guide](https://documentation.meraki.com/MI/Meraki_MX_ThousandEyes_Configuration_Guide).

## Connectivity

The Meraki device will need to be able to connect to the ThousandEyes platform's cloud infrastructure. For more information, see [Firewall Configuration for Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/firewall-configuration-for-enterprise-agents).

In addition to the standard firewall configuration, Meraki devices will need to reach the following cloud endpoint via HTTPS:

* registry.meraki-applications.com

## Installation and Setup

Installation and setup instructions can be found here: [Meraki ThousandEyes Configuration Guide](https://documentation.meraki.com/MI/Meraki_MX_ThousandEyes_Configuration_Guide).

## Limitations

* Transaction and page load tests are not supported.
* Using an Enterprise Agent installed on a Meraki device as the target agent of an agent to agent test / RTP test is not supported.
* vMX is not supported.
* Meraki EU region’s organization can only be mapped to ThousandEyes EU accounts.
* All non-EU Meraki organizations can only be linked to ThousandEyes US accounts.
* Meraki agents use the default uplink interface `0.0.0.0/0` route for connecting to the ThousandEyes platform. For more information on routing policies, see [Meraki Routing Behavior](https://documentation.meraki.com/MX/Networks_and_Routing/MX_Routing_Behavior).

{% hint style="warning" %}
We do not recommend running agent to agent tests with the throughput measurement as it may impact the performance of Meraki devices.
{% endhint %}

## Account Restrictions

* ThousandEyes **Account Admin** users with the *local auth permission* can link two accounts.
* Users who have active ThousandEyes user accounts cannot create a new ThousandEyes account as part of the workflow.
* The Meraki dashboard organization needs to have at least two administrators.


# Cisco Enterprise NFV Infrastructure Software

ThousandEyes supports installing Enterprise Agents on supported Cisco Catalyst routers and UCS-C rack servers using Cisco Enterprise Network Functions Virtualization Infrastructure Software (NFVIS).

This article outlines the system requirements and supported devices for Cisco NFVIS.

## Overview

ThousandEyes Enterprise Agents can be installed as a container within your NFVIS environment, allowing you to leverage ThousandEyes monitoring and testing capabilities for end-to-end visibility into the performance of the underlying network infrastructure.

For more information about Cisco NFVIS, see here: [Cisco NFVIS](https://www.cisco.com/c/en/us/products/routers/enterprise-nfv-infrastructure-software/index.html).

## Supported Devices and System Requirements

| Cisco Catalyst Router              | Supported Test Types  | NFVIS Requirements             |
| ---------------------------------- | --------------------- | ------------------------------ |
| C8200 uCPE                         | All non-browser tests | NFVIS version 4.15.2 and later |
| C8300 uCPE                         | All non-browser tests | NFVIS version 4.15.2 and later |
| NFVIS supported UCS-C rack servers | All non-browser tests | NFVIS version 4.15.2 and later |

## Installation Instructions

Refer to the Cisco documentation links and instructions below to deploy ThousandEyes on Cisco NFVIS:

* [Install Enterprise Agents on Cisco Routers using NFVIS and the Cisco Catalyst SD-WAN Manager](https://www.cisco.com/c/en/us/td/docs/routers/nfvis/config/sd-branch-4/b-NFV-vManage-solution-guide/m-thousand-eyes-container-support-sd-branch.html)
* [Install Enterprise Agents on Cisco Routers using the NFVIS Web UI](https://www.cisco.com/c/en/us/td/docs/routers/nfvis/config/nfvis-4/nfvis-config-guide-4/m-cisco-nfvis-thousandeyes-support.html)
* [Install Enterprise Agents on Cisco Routers using NFVIS Standalone CLI](#install-enterprise-agents-on-cisco-routers-using-nfvis-and-the-thousandeyes-cli)

{% hint style="info" %}
ThousandEyes recommends using the SD-WAN Manager for installing Enterprise Agents on Cisco routers using NFVIS.
{% endhint %}

### Install Enterprise Agents on Cisco Routers using NFVIS and the ThousandEyes CLI

To install a ThousandEyes Enterprise Agent on NFVIS using the CLI:

1. Configure the Docker image registration details. An example configuration is shown below. Ensure you replace the `src` URL with the URL provided in the **Add New Enterprise Agent** dialog:

   ```
   vm_lifecycle images image thousandeyes-enterprise-agent
    src https://downloads.thousandeyes.com/enterprise-agent/thousandeyes-enterprise-agent-VERSION-nfvis.docker
    locator vim_id container
    properties property low_latency
     value false
    !
    properties property placement
     value datastore1
    !
    properties property vnf_type
     value THOUSANDEYES
    !
    
   !
   ```
2. Configure the resource details as a flavor:

   ```
   vm_lifecycle flavors flavor thousandeyes-flavor vcpus 2 memory_mb 2048 root_disk_mb 20480
   !
   ```
3. Configure the ThousandEyes Enterprise Agent container deployment details, replacing `ACCOUNT_GROUP_TOKEN` with your account group token:

   ```
   vm_lifecycle tenants tenant admin
    deployments deployment TE_DEMO
     vm_group TE_DEMO
      vim_vm_name  TE_DEMO
      locator vim_id container
      image       thousandeyes-enterprise-agent
      flavor      thousandeyes-flavor
      bootup_time -1
      config_data configuration bootstrap_config
       data            "{ \"env_variables\" : { \"TEAGENT_ACCOUNT_TOKEN\" : \"${TEAGENT_ACCOUNT_TOKEN}\", \"TEAGENT_INET\" : \"4\"} }"
       template_engine VELOCITY
       variable TEAGENT_ACCOUNT_TOKEN
        val [ ACCOUNT_GROUP_TOKEN ]
       !
     !
    !
   !
   ```
4. Commit the configurations.


# Installation Methods


# Installing Enterprise Agents on Cisco Nexus Switches with Application Hosting

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

This article covers the steps to install a ThousandEyes Enterprise Agent on supported Cisco Nexus switches using Cisco Application Hosting.

## Prerequisites

* A ThousandEyes account with permissions to install new agents. For more information on setting up a ThousandEyes account, see [Getting Started with Account Setup](https://docs.thousandeyes.com/product-documentation/getting-started/getting-started-with-account-setup).
* A supported Cisco Nexus switch. For more information on supported devices, see the [Nexus Switching Support Matrix](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices).

{% hint style="warning" %}
The ThousandEyes for Government instance has additional requirements for Cisco Application Hosting installations. Refer to the [ThousandEyes for Government - FedRAMP® Moderate](https://docs.thousandeyes.com/product-documentation/thousandeyes-for-government#cisco-application-hosting) documentation for prerequisites and configuration requirements **before** continuing.
{% endhint %}

## Installation Instructions

1. Log into the ThousandEyes web application.
2. Navigate to **Network & App Synthetics > Agent Settings > Enterprise Agents > Agents**.
3. Click **Add New Enterprise Agent**.
4. In the pop out panel, navigate to **Cisco Application Hosting > Nexus Switches**.

   ![](/files/Qhpzh7DOgHplhyUwaFWX)

{% hint style="info" %}
The screenshot above shows a bridge configuration. For additional app-hosting configuration options, see the [Nexus Application Hosting documentation](https://www.cisco.com/c/en/us/td/docs/dcn/nx-os/nexus9000/103x/programmability/cisco-nexus-9000-series-nx-os-programmability-guide-release-103x/m-application-hosting.html).
{% endhint %}

## Download the TAR File

The TAR file can either be downloaded directly to the switch by using the NX-OS `copy` command, or downloaded via a web browser from the ThousandEyes webapp and then transferred to the Nexus switch:

{% hint style="info" %}
ThousandEyes recommends using the `copy` command if possible, as it reduces the download process to a single step, and will also verify access to *thousandeyes.com* from the switch.
{% endhint %}

{% hint style="info" %}
Depending on your network configuration, you may need to specify which VRF to use to reach *downloads.thousandeyes.com* as part of the `copy` command.
{% endhint %}

### Copy Command

1. In a terminal window on the Cisco Nexus switch, run the `copy` command shown in the ThousandEyes webapp to download the TAR file. It should look something like this:

   `copy https://downloads.thousandeyes.com/enterprise-agent/thousandeyes-enterprise-agent-VERSION.cisco.tar bootflash:`

{% hint style="warning" %}
If you encounter an error running the copy command, follow the instructions in [Browser Download](#browser-download) instead.
{% endhint %}

### Browser Download

1. From the **Cisco Application Hosting > Nexus Switches** screen, click the **Download - TAR** button.
2. In a terminal window, use SCP, FTP, TFTP, or USB storage to copy the TAR file to the switch's bootflash: directory. We recommend using the same method used to copy the NX-OS system software image onto the switch. For more information, see [Installing NX-OS](https://www.cisco.com/c/en/us/td/docs/dcn/nx-os/nexus9000/103x/upgrade/cisco-nexus-9000-nx-os-software-upgrade-downgrade-guide-103x/m_upgrading_or_downgrading_the_cisco_nexus_9000_series_nx-os_software_101x.html).

## Generate and Run Commands

1. From the **Cisco Application Hosting > Nexus Switches** screen, configure the required fields (and any optional ones you want) to generate the basic command structure for installing and starting the agent:

   ![](/files/25pUBYd3TzZmlK1xTZ6v)

   * **App ID**: The name used in the NX-OS CLI to manage the application hosting container.
   * **Bridge ID**: The number of the application hosting bridge instance created to connect the container to an L3 network on the switch. For more information, see [Configuring Application Hosting Bridge Connections](https://www.cisco.com/c/en/us/td/docs/dcn/nx-os/nexus9000/103x/programmability/cisco-nexus-9000-series-nx-os-programmability-guide-release-103x/m-application-hosting.html#task_rxd_45x_g5b).
   * **IP Address**: The IP address assigned to the interface inside the container.
   * **Agent Hostname (Optional)**: The hostname assigned to the agent within the container. By default, this is the same hostname as the switch.
   * **Name Server IP**: The DNS IP address used within the container.
   * **Gateway IP**: The default gateway IP address used within the container. This is usually the IP address of the application hosting bridge.
   * **Name Server IP 2 (Optional)**: An alternate DNS IP address.
2. Once the basic commands have been pre-configured, copy them from the web browser to a local machine.
3. Edit and expand the commands as necessary. Additional run-opts commands can be added as needed. For available commands, see [Docker Agent Configuration Options](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/docker-agent-config-options).
4. Once the commands are ready, in a terminal window on the Nexus switch, run the commands in order from top to bottom, excluding the **copy** command.

## Limitations

* NX-OS version 10.3(3) and earlier does not support configuring multiple interfaces.

## Troubleshooting

#### NX-OS Copy Command Does Not Work With HTTPS

There is an existing bug that prevents the NX-OS `copy` command from working with HTTPS. This prevents users from downloading the ThousandEyes Enterprise Agent TAR file directly to the device.

**Workaround**

To workaround this issue, we recommend you download the TAR file, and then copy it to the switch using the same method used for copying the NX-OS system software image to the device.


# Installing Enterprise Agents on Cisco Routers using SD-WAN Manager Feature Templates

This article covers the steps to install a ThousandEyes Enterprise Agent on Cisco routers running in SD-WAN mode that are managed by Cisco SD-WAN Manager (formerly Cisco vManage). For more information about SD-WAN Manager, see the [SD-WAN Manager Documentation](https://www.cisco.com/site/us/en/products/networking/wan/vmanage/index.html).

{% hint style="info" %}
vEdge routers must be added to the SD-WAN Manager inventory list before continuing. For more information, see the [SD-WAN Manager Documentation](https://sdwan-docs.cisco.com/Product_Documentation/vManage_Help/Release_18.3/Configuration/Devices).
{% endhint %}

{% hint style="info" %}
As a part of container package best practices, we recommend updating your container regularly.
{% endhint %}

## Prerequisites

To review the supported Cisco routers and hardware requirements, see the [Support Matrix](https://docs.thousandeyes.com/product-documentation/integration-guides/thousandeyes-cisco-integration#support-matrix).

## Installation Steps

### Log into the Portal

1. Log into the SD-WAN Manager portal.
2. Navigate to **Maintenance > Software Repository**.

   ![](/files/2bQxjwckScVG1MdXdGPE)

### 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 > SD-WAN Manager**.

   ![](/files/3EJPWVjftE0FEleu8DkJ)
3. Upload the ThousandEyes installation image .tar file as an Image Package:

   ![](/files/LB3P0pqfVeGVnxZ043rC)

**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:

![](/files/MB7RB5kvUdrh1PD5hUJM)

![](/files/zNvpmDmh3Src4PsoXZsj)

### 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**.

   ![](/files/oDRhmeUYowfI3IDeFSJk)
3. Under **Select Device**, search for the device model (for example, ISR4431) that you wish to deploy an agent to. See the [Support Matrix](https://docs.thousandeyes.com/product-documentation/integration-guides/thousandeyes-cisco-integration#support-matrix) for compatible routers.
4. Select **ThousandEyes Agent** template from under **Other Templates**.

   ![](/files/plLihzIs30lecRiEfPBL)
5. Specify the template name and description.

   ![](/files/wxah8CFA068R7ZtEAyrh)
6. Under **Basic Configuration**, enter the relevant **Account Group Token**.

   ![](/files/AmaZ8vglSL7yoMbFyVUT)
7. **Optional:** SD-WAN mode allows you to send agent traffic to pre-configured VPN tunnels instead of following the default management route. ThousandEyes supports using the service VPN configuration. Specify the template (either Default, Global, or Device Specific) to deploy the ThousandEyes agent within.

   This will allow you to configure tests that measure end-to-end application experience through both the SD-WAN fabric and direct Internet access. This will also allow you to test the SD-WAN underlay paths through multiple transport networks by configuring additional traffic rules.

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

   **Note:** Avoid placing the ThousandEyes agent within VPN 0 as it will limit your ability to test desired networks and services.
8. Under **Advanced**, configure the **Name Server**, **Hostname**, and **Web Proxy**.

![](/files/xj8aAkQvekKwG4hyYaqL)

**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**.

   ![](/files/49Bxl77J1Nn4UNTVup4j)
3. Navigate to the **Additional Template**.
4. Open the **ThousandEyes Agent** drop-down menu, and select the template created in steps 2-9.

   ![](/files/oIo6qzFuE024RA4b05zS)
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**.

   ![](/files/QvO8pbJQkgnPoadP7pch)
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.

   ![](/files/XZ58L3y1uGJioe8oVbY3)

### 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**.

   ![](/files/PNxOPcaif6OLknFV2rix)

   ![](/files/Owi7sd4CeO3ZuhzWGz9p)

### Agent Management

Agents can be un-deployed by removing the ThousandEyes Agent feature template from the device template. However, SD-WAN Manager 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](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/installing-enterprise-agents-on-cisco-routers#reconfigure-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 **pool.ntp.org** 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 (pool.ntp.org) be changed to a customer's internal NTP source?**

No. The agent uses **pool.ntp.org** 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
```

{% hint style="info" %}
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.
{% endhint %}

For more information on configuration options, see [Docker Agent Config Options](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/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](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/troubleshooting/cli-network-troubleshooting-utilities).


# Installing Enterprise Agents on Cisco Routers using the SD-WAN Manager ThousandEyes Workflow

Cisco ThousandEyes supports connecting your Cisco SD-WAN Manager instance to the ThousandEyes platform, to simplify the deployment and management of Enterprise Agents and their associated ThousandEyes tests.

{% hint style="info" %}
You will need ThousandEyes organization admin permissions to link your SD-WAN Manager instance to the ThousandEyes platform, as the process uses OAuth2 to connect a specific account group within your ThousandEyes organization to your SD-WAN Manager instance. For more information, see the installation instructions linked below.
{% endhint %}

## Prerequisites

* SD-WAN Manager version 20.16 or later.
* ThousandEyes Organization Admin permissions.

## Installation Instructions

* [SD-WAN Instructions](https://www.cisco.com/c/en/us/td/docs/routers/sdwan/configuration/system-interface/ios-xe-17/systems-interfaces-book-xe-sdwan/m-onboarding-thousandeye-agent-and-config-test.html)


# Installing Enterprise Agents on Cisco Switches with Docker

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

This article walks users through the steps to install a ThousandEyes Enterprise Agent on a Cisco Catalyst 9000-series switch with Docker, using the command line. The Enterprise Agent is a signed ThousandEyes Docker image that can be launched using Cisco application hosting.

{% hint style="info" %}
The agent can also be installed using the [Cisco DNA Center](https://www.cisco.com/site/id/en/products/networking/dna-center-platform/resources.html).
{% endhint %}

{% hint style="info" %}
As a part of container package best practices, we recommend updating your container regularly.
{% endhint %}

## Overview

To support application hosting capabilities on Cisco Catalyst 9000-series switches, the switch provides hardware resources where applications can reside and execute. Cisco IOS XE reserves dedicated memory and CPU resources for application hosting to provide a separate execution space for user applications, without compromising the integrity and performance of the switch.

The Cisco IOS XE 16.12.1 release introduced native Docker container support on Catalyst 9000-series switches. The ThousandEyes Enterprise Agent leverages this capability to run a Docker container hosted on internal flash storage (if no SSD is available).

Container connectivity is described in the image below. Containers can be connected via the management interface and front panel data ports. The management interface connects to the container interface via the management bridge, and the IP address of the container will be on the same subnet as the management interface. Virtual network interface cards (vNICs) inside containers are seen as standard Ethernet interfaces (**eth0**, **eth1**, etc.).

![](/files/-MUS86UB3BCLZkXT6g3Q)

For more information on Cisco application hosting, see [Application Hosting](https://www.cisco.com/c/en/us/products/collateral/switches/catalyst-9300-series-switches/white-paper-c11-742415.html).

## Requirements

For detailed requirements for installing Enterprise Agents on Cisco Catalyst switches, see the [Support Matrix](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices#support-matrix).

{% hint style="warning" %}
The ThousandEyes for Government instance has additional requirements for Cisco Application Hosting installations. Refer to the [ThousandEyes for Government - FedRAMP® Moderate](https://docs.thousandeyes.com/product-documentation/thousandeyes-for-government#cisco-application-hosting) documentation for prerequisites and configuration requirements **before** continuing.
{% endhint %}

## Installation Steps

{% hint style="info" %}
ThousandEyes supports configuring multiple interfaces on Cisco Catalyst devices. For more information, see [Multi-Interface Support for Cisco Catalyst 9000 Switches](#multi-interface-support-for-cisco-catalyst-9000-switches).
{% endhint %}

### Downloading the Docker Image

Download the Docker image from the ThousandEyes dashboard and copy it to your Cisco switch using SCP, FTP, TFTP, or USB storage.

{% hint style="info" %}
If the switch has internet access, download the image directly onto the switch. Download the package from the [ThousandEyes downloads site](https://downloads.thousandeyes.com/enterprise-agent/thousandeyes-enterprise-agent-4.4.2.cisco.tar).
{% endhint %}

1. Log in to the ThousandEyes platform using a login belonging to the account group that will be associated with the appliance.
2. Go to **Network & App Synthetics > Agent Settings** and click **Add New Enterprise Agent**.
3. Download the **.tar** file with the ThousandEyes appliance for Catalyst 9000-series switches.
4. Use SCP, FTP, TFTP, or USB storage to copy the signed Docker image to the switch's **flash:** directory.

   ```
   copy scp://thousandeyes@10.100.21.239/thousandeyes-enterprise-agent-4.4.2.cisco.tar flash:
   ```
5. Run a checksum (**md5**) command to verify that the package transfer was successful. The **md5** output should match `14b88bfc3ec75a2ff4414d8f39106a29`:

   ```
   catalyst#verify /md5 flash:thousandeyes-enterprise-agent-4.4.2.cisco.tar
   -----------------------------------------------------------
   verify /md5 (flash:thousandeyes-enterprise-agent-4.4.2.cisco.tar) = 14b88bfc3ec75a2ff4414d8f39106a29
   ```

### Installing the Docker Container

1. Enable the IOx framework on the switch:

   ```
   Enter configuration commands, one per line.  End with CNTL/Z.
   catalyst(config)#iox
   catalyst(config)#end
   ```
2. Wait until all the services are running:

   ```
   catalyst#show iox-service
   ​IOx Infrastructure Summary:
   ---------------------------
   IOx service (CAF) 1.11.0.5     : Running
   IOx service (HA)               : Running
   IOx service (IOxman)           : Running
   IOx service (Sec storage)      : Not Running
   Libvirtd 1.3.4                 : Running
   Dockerd 18.03.0                : Running
   Application DB Sync Info       : Available
   Sync Status                    : Disabled
   ```
3. Run the **install** command:

   `catalyst#app-hosting install appid <app-name> package flash:thousandeyes-enterprise-agent-4.4.2.cisco.tar`

   Specify your desired app name and the location of the image file you want to use. In this example, we use **thousandeyes\_enterprise\_agent**.
4. If the image is hosted on an HTTPS server, you can run the following command to download the image:

   ```
   catalyst#app-hosting install appid <app-name> package https://downloads.thousandeyes.com/enterprise-agent/thousandeyes-enterprise-agent-4.4.2.cisco.tar
   ```
5. Your application should now be installed. You can check on it by running the following:

   ```
   catalyst#sh app-hosting list
   App id State
   thousandeyes_enterprise_agent DEPLOYED
   ```

### Configuring the Docker Container

Docker supports both guest IP address assignment and dynamic IP address assignment. You must configure a single virtual network interface card (vNIC) for the appliance that would allow the Layer-2 VLAN routed from the uplink switch and router to be assigned to the container.

{% hint style="warning" %}
Ensure that the Layer-2 VLAN has been passed through from any active physical port and is not the default VLAN used in the switch (usually VLAN 1).
{% endhint %}

1. Verify that the front panel data port is running, with Layer-2 VLAN allowed from uplink:

   ```
   catalyst(config)#interface GigabitEthernet1/0/13
   catalyst(config-if)#description Uplink MGMT
   catalyst(config-if)#switchport access vlan 21
   ```
2. Verify that the Layer-2 VLAN is created:

   ```
   catalyst(config)#vlan 21
   ```
3. Configure the AppGigabitEthernet port to allow Layer-2 VLAN:

   ```
   catalyst(config)#interface AppGigabitEthernet1/0/1
   catalyst(config-if)#switchport trunk allowed vlan 21,22,23,24
   catalyst(config-if)#switchport mode trunk
   ```
4. Configure the application, either with a static IP or with DHCP IP.

   **Configuration with Static IP**

   Use a guest IP address to assign a static IP address. In this example, assign **10.100.21.222/24**, under VLAN 21 and use Google resolver:

   ```
   catalyst(config)#app-hosting appid thousandeyes_enterprise_agent
   catalyst(config-app-hosting)#app-vnic AppGigabitEthernet trunk
   catalyst(config-config-app-hosting-trunk)#vlan 21 guest-interface 0
   catalyst(config-config-app-hosting-vlan-access-ip)#guest-ipaddress 10.100.21.222 netmask 255.255.255.0
   catalyst(config-config-app-hosting-vlan-access-ip)#exit
   catalyst(config-config-app-hosting-trunk)#exit
   catalyst(config-app-hosting)#app-default-gateway 10.100.21.1 guest-interface 0
   catalyst(config-app-hosting)#name-server0 8.8.8.8
   catalyst(config-app-hosting)#name-server1 8.8.4.4
   ```

   Next, set up the required Docker run options to specify account token. If you want to specify a hostname other than the switch's name, do this here as well:

   ```
   catalyst(config-app-hosting)#app-resource docker
   catalyst(config-app-hosting-docker)#prepend-pkg-opts
   catalyst(config-app-hosting-docker)#run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN=<Token>"
   catalyst(config-app-hosting-docker)#run-opts 2 "--hostname Cisco-Docker"
   catalyst(config-app-hosting-docker)#exit
   catalyst(config-app-hosting)#start
   catalyst(config-app-hosting)#end
   ```

   **Configuration with DHCP IP**

   Make sure the DHCP server is running on the layer-2 VLAN. In this case, assign a DHCP address under VLAN 21 and use Google resolver:

   ```
   catalyst(config)#app-hosting appid thousandeyes_enterprise_agent
   catalyst(config-app-hosting)#app-vnic AppGigabitEthernet trunk
   catalyst(config-config-app-hosting-trunk)#vlan21 guest-interface 0
   ```

   Next, set up the required Docker run options to specify the account token. If you want to specify a hostname other than the switch's name, do this here as well:

   ```
   catalyst(config-config-app-hosting-vlan-access-ip)#app-resource docker
   catalyst(config-app-hosting-docker)#prepend-pkg-opts
   catalyst(config-app-hosting-docker)#run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN=<Token>"
   catalyst(config-app-hosting-docker)#run-opts 2 "--hostname Cisco-Docker"
   catalyst(config-app-hosting-docker)#name-server0 8.8.8.8
   catalyst(config-app-hosting-docker)#exit
   catalyst(config-app-hosting)#start
   catalyst(config-app-hosting)#end
   ```

   For a full list of the Docker configuration options, see [Docker Agent Configuration Options](/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/installation-methods/installing-enterprise-agents-on-cisco-switches-with-docker).
5. Use **wr mem** to ensure that your configuration changes have persisted across reboots:

   ```
   catalyst#wr mem
   Building configuration...
   [OK]
   ```

### Verifying That the Docker Container Is Running

With the `(config-app-hosting)#start` command, the Docker container should have been started and should be running.

1. Verify this by running the following:

   ```
   catalyst# sh app-hosting list
   App id                                   State
   ---------------------------------------------------------
   thousandeyes_enterprise_agent            RUNNING
   ```
2. Verify the Docker container’s details:

   ```
   catalyst#show app-hosting detail appid thousandeyes_enterprise_agent
   App id                 : thousandeyes_enterprise_agent
   Owner                  : iox
   State                  : RUNNING
   Application
      Type                 : docker
      Name                 : ThousandEyes Enterprise Agent
      Version              : 4.4.2
      Description          : 
      Author               : ThousandEyes <support@thousandeyes.com>
      Path                 : flash:thousandeyes-enterprise-agent-4.4.2.cisco.tar
      URL Path             : 
   Activated profile name : custom

   Resource reservation
     Memory               : 500 MB
     Disk                 : 1 MB
     CPU                  : 1850 units
     VCPU                 : 1
   Attached devices
     Type              Name               Alias
   ---------------------------------------------
     serial/shell     iox_console_shell   serial0
     serial/aux       iox_console_aux     serial1
     serial/syslog    iox_syslog          serial2
     serial/trace     iox_trace           serial3

   Network interfaces
     ---------------------------------------
   eth0:
     MAC address         : 52:54:dd:d:38:3d
     Network name        : mgmt-bridge-v21
   Docker
   ------
   Run-time information
     Command              :
     Entry-point          : /sbin/my_init
     Run options in use   : -e TEAGENT_ACCOUNT_TOKEN=TOKEN_NOT_SET
   --hostname=$(SYSTEM_NAME) --cap-add=NET_ADMIN --mount
   type=tmpfs,destination=/var/log/agent,tmpfs-size=140m --mount
   type=tmpfs,destination=/var/lib/te-agent/data,tmpfs-size=200m -v
   $(APP_DATA)/data:/var/lib/te-agent -e TEAGENT_PROXY_TYPE=DIRECT -e
   TEAGENT_PROXY_LOCATION= -e TEAGENT_PROXY_USER= -e
   TEAGENT_PROXY_AUTH_TYPE= -e TEAGENT_PROXY_PASS= -e
   TEAGENT_PROXY_BYPASS_LIST= -e TEAGENT_KDC_USER= -e TEAGENT_KDC_PASS=
   -e TEAGENT_KDC_REALM= -e TEAGENT_KDC_HOST= -e TEAGENT_KDC_PORT=88 -e
   TEAGENT_KERBEROS_WHITELIST= -e TEAGENT_KERBEROS_RDNS=1 -e PROXY_APT=
   -e APT_PROXY_USER= -e APT_PROXY_PASS= -e APT_PROXY_LOCATION= -e
   TEAGENT_AUTO_UPDATES=1 -e
   TEAGENT_ACCOUNT_TOKEN=nfhjzm8e8ikg07d4n31wcsws9bakcloh --hostname
   Cisco-Docker

     Package run options  : -e TEAGENT_ACCOUNT_TOKEN=TOKEN_NOT_SET
   --hostname=$(SYSTEM_NAME) --cap-add=NET_ADMIN --mount
   type=tmpfs,destination=/var/log/agent,tmpfs-size=140m --mount
   type=tmpfs,destination=/var/lib/te-agent/data,tmpfs-size=200m -v
   $(APP_DATA)/data:/var/lib/te-agent -e TEAGENT_PROXY_TYPE=DIRECT -e
   TEAGENT_PROXY_LOCATION= -e TEAGENT_PROXY_USER= -e
   TEAGENT_PROXY_AUTH_TYPE= -e TEAGENT_PROXY_PASS= -e
   TEAGENT_PROXY_BYPASS_LIST= -e TEAGENT_KDC_USER= -e TEAGENT_KDC_PASS=
   -e TEAGENT_KDC_REALM= -e TEAGENT_KDC_HOST= -e TEAGENT_KDC_PORT=88 -e
   TEAGENT_KERBEROS_WHITELIST= -e TEAGENT_KERBEROS_RDNS=1 -e PROXY_APT=
   -e APT_PROXY_USER= -e APT_PROXY_PASS= -e APT_PROXY_LOCATION= -e
   TEAGENT_AUTO_UPDATES=1

   Application health information
     Status               : 0
     Last probe error     :
     Last probe output    :
   ```
3. In the ThousandEyes platform, go to **Network & App Synthetics > Agent Settings** and verify the Docker container’s IP address:

   ![](/files/-Mk3-1JWrK2u0DSxDJFo)

### Assigning the Agent to Tests

Now that you have installed, configured, and started your Docker-based agent, you can create tests and assign them to be run by your new agent. For instructions, see [Getting Started with Tests](https://docs.thousandeyes.com/product-documentation/getting-started#create-a-test).

## Modify the Docker Container

1. Stop the application:

   ```
   catalyst# app-hosting stop appid thousandeyes_enterprise_agent
   thousandeyes_enterprise_agent stopped successfully
   Current state is: STOPPED
   ```
2. De-activate the application:

   ```
   catalyst# app-hosting deactivate appid thousandeyes_enterprise_agent
   thousandeyes_enterprise_agent deactivated successfully
   Current state is: DEPLOYED
   ```
3. Modify the Docker options, and exit three times:

   ```
   catalyst(config)#app-hosting appid thousandeyes_enterprise_agent
   catalyst(config-app-hosting)#app-resource docker
   catalyst(config-app-hosting-docker)#prepend-pkg-opts
   catalyst(config-app-hosting-docker)#<run-opts command>
   catalyst(config-app-hosting-docker)#exit
   catalyst(config-app-hosting)#exit
   catalyst(config)#exit
   ```
4. Reactivate the application, and confirm that it’s activated:

   ```
   catalyst# app-hosting activate appid thousandeyes_enterprise_agent
   thousandeyes_enterprise_agent activated successfully
   Current state is: ACTIVATED
   ```
5. Start the application, and confirm that it is running:

   ```
   catalyst# app-hosting start appid thousandeyes_enterprise_agent
   thousandeyes_enterprise_agent started successfully
   Current state is: RUNNING
   ```

## Multi-Interface Support for Cisco Catalyst 9000 Switches

ThousandEyes supports configuring multiple interfaces on Cisco Catalyst devices, allowing Cisco Catalyst Enterprise Agents to access multiple virtual networks with the same Enterprise Agent. Once configured, users can select which interface to use for a test from the agent selection UI.

For more information on interface selection, see [Enterprise Agent Interface Selection](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/enterprise-agent-interface-selection).

### Supported Devices

The following devices are supported for configuring multiple interfaces:

* Cisco Catalyst 9300
* Cisco Catalyst 9400

For more information on supported Cisco devices, see the [Support Matrix](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices#support-matrix).

### Prerequisites

The app-hosting container on the Cisco Switch must be using image version 4.3.0 or later for multi-interface support.

For more detailed requirements for installing Enterprise Agents on Cisco Catalyst 9000-series switches, see the [Support Matrix](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices#support-matrix).

### Configuration

{% hint style="warning" %}
To avoid any ARP issues, ThousandEyes suggests limiting your environment to one guest IP address per VLAN in the app-vnic configuration.
{% endhint %}

To configure multiple interfaces, you need to configure one or more additional guest-interfaces and associate them with the relevant networks or VLANs by using the **app-default-gateway** configuration command. Once configured, you can run tests over the additional interfaces by specifying the default gateways for each of the networks associated with these interfaces, using environment variables in the container to specify the default gateway address, guest-ipaddress, and VLAN ID. The environment variables should follow the following naming convention, where X is any value in the range of 0-7, and corresponds to the number of the guest interface in the container configuration:

```
TEAGENT_DEF_IPV4_GW_ETH<X>
```

1. If reconfiguring an existing container, first stop the application:

   ```
   catalyst# app-hosting stop appid thousandeyes_enterprise_agent
   thousandeyes_enterprise_agent stopped successfully
   Current state is: STOPPED
   ```
2. De-activate the application:

   ```
   catalyst# app-hosting deactivate appid thousandeyes_enterprise_agent
   thousandeyes_enterprise_agent deactivated successfully
   Current state is: DEPLOYED
   ```
3. Modify the container:

   ```
   app-hosting appid cat9k402
      app-vnic AppGigabitEthernet trunk
         vlan 21 guest-interface 0
            guest-ipaddress 10.100.21.65 netmask 255.255.255.0
         vlan 22 guest-interface 1
            guest-ipaddress 10.100.22.65 netmask 255.255.255.0
         vlan 23 guest-interface 2
            guest-ipaddress 10.100.23.65 netmask 255.255.255.0
         vlan 24 guest-interface 3
            guest-ipaddress 10.100.24.65 netmask 255.255.255.0
            
      app-default-gateway 10.100.21.1 guest-interface 0
   app-resource docker
      prepend-pkg-opts
         run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN={}"
         run-opts 2 "--hostname cat9k-multi"
         run-opts 3 "-e TEAGENT_DEF_IPV4_GW_ETH1=10.100.22.10"
         run-opts 4 "-e TEAGENT_DEF_IPV4_GW_ETH2=10.100.23.10"
         run-opts 5 "-e TEAGENT_DEF_IPV4_GW_ETH3=10.100.24.10"
         name-server0 8.8.8.8
         name-server1 10.100.50.102
   ```
4. Exit three times to completely exit out of config mode.
5. Use **wr mem** to ensure the changes are persistent across reboots.

Once the configuration has been saved, reactivate and restart the container to apply the app-hosting configuration changes.

The image below show the configured routing table in the ThousandEyes web app, in **Network & App Synthetics > Agent Settings > Selected Agent > System Information > Routing Table**:

![](/files/J0PV0RLEuVYDSGDcxuSs)

### Limitations

* This process is only supported for Cisco Application Hosting and Cisco DNA Center, not SD-WAN Manager.
* Browserbot related tests (page load and transaction) are not supported.
* DNS tests are not supported. DNS requests will continue to be sent via default route and source address.
* Agent to agent tests are not supported, as there is no interface selection for the return path. The response will continue to use the default route.

## Frequently Asked Questions

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

The enterprise agent on a Catalyst 9000 series switch uses the host system kernel clock. It also sends packets to **pool.ntp.org** 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 (pool.ntp.org) be changed to a customer's internal NTP source?**

Yes. For configuration steps, see [NTP Server Configuration on the Cisco Application Hosting Framework Agents (CAF)](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/advanced-configuration-options-for-caf-agents#ntp-server-configuration-on-the-cisco-application-hosting-framework-agents-caf).

**What happens if the primary switch in my HA mode stack fails?**

When a Cat9k switch is deployed in HA mode (stacked), for the first 30 minutes, if the primary switch in the stack fails, and a secondary switch takes over, a new agent will be brought up, and the original agent on the failed switch will go offline. After the first 30 minutes, there will be seamless agent failover that preserves agent identity.

**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
```

{% hint style="info" %}
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.
{% endhint %}

For more information on configuration options, see [Docker Agent Config Options](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/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](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/troubleshooting/cli-network-troubleshooting-utilities).

**What are the default trusted default root certificates used by the Enterprise Agent Docker container when communicating with ThousandEyes services?**

* issuer=O = Cisco, CN = Cisco Licensing Root CA
* issuer=O = Cisco, CN = Cisco Basic Assurance Root CA 2099
* issuer=O = Cisco, CN = Cisco ECC Root CA
* issuer=O = Cisco Systems, CN = Cisco Root CA 2048
* issuer=O = Cisco, CN = Cisco Root CA 2099
* issuer=O = Cisco, CN = Cisco Root CA M1
* issuer=O = Cisco, CN = Cisco Root CA M2
* issuer=C = US, O = Cisco Systems, CN = Cisco RXC-R2
* issuer=C = US, O = Amazon, CN = Amazon Root CA 1
* issuer=C = US, O = Amazon, CN = Amazon Root CA 2
* issuer=C = US, O = Amazon, CN = Amazon Root CA 3
* issuer=C = US, O = Amazon, CN = Amazon Root CA 4
* issuer=C = NO, O = Buypass AS-983163327, CN = Buypass Class 2 Root CA
* issuer=C = US, O = DigiCert Inc, OU = [www.digicert.com](http://www.digicert.com), CN = DigiCert Global Root CA
* issuer=C = US, O = Internet Security Research Group, CN = ISRG Root X1
* issuer=C = US, O = IdenTrust, CN = IdenTrust Commercial Root CA 1
* issuer=C = BM, O = QuoVadis Limited, CN = QuoVadis Root CA 2
* issuer=C = US, ST = New Jersey, L = Jersey City, O = The USERTRUST Network, CN = USERTrust ECC Certification Authority
* issuer=C = US, ST = New Jersey, L = Jersey City, O = The USERTRUST Network, CN = USERTrust RSA Certification Authority
* issuer=C = US, O = Google Trust Services LLC, CN = GTS Root R1
* issuer=C = US, O = Google Trust Services LLC, CN = GTS Root R2
* issuer=C = US, O = Google Trust Services LLC, CN = GTS Root R3
* issuer=C = US, O = Google Trust Services LLC, CN = GTS Root R4

**How do I install CA certificates on Cisco devices?**

For CA certificate installation instructions, see [Installing CA Certificates on Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/troubleshooting/installing-ca-certificates-on-enterprise-agents#installing-on-cisco-docker-devices).

**For multi-interface support, which interface is used for the agent default registration? Can I change that?**

**eth0** is used, and is specified in the configuration as 'guest-interface 0". It is possible to change the interface used by using the `app-default-gateway` config command to set the default route in the container.

**For multi-interface support, is there a limitation on the number of configurable interfaces?**

ThousandEyes supports using up to 8 interfaces on Catalyst 9300 and 9400 switches.


# Installing Enterprise Agents on Cisco Routers with Docker

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

This article provides a walkthrough for installing a ThousandEyes Enterprise Agent on a supported Cisco router. The agent is included in a ThousandEyes Docker image packaged in a signed tar file specific for installation using Cisco application hosting.

{% hint style="info" %}
As a part of container package best practices, we recommend updating your container regularly.
{% endhint %}

## Prerequisites

Review the supported devices and hardware requirements before continuing with the installation instructions:

* [Catalyst Routers](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/catalyst-routers)
* [Industrial Routers](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices/industrial-routers)

{% hint style="info" %}
Both SD-WAN and Autonomous mode are supported.
{% endhint %}

{% hint style="warning" %}
The ThousandEyes for Government instance has additional requirements for Cisco Application Hosting installations. Refer to the [ThousandEyes for Government - FedRAMP® Moderate](https://docs.thousandeyes.com/product-documentation/thousandeyes-for-government#cisco-application-hosting) documentation for prerequisites and configuration requirements **before** continuing.
{% endhint %}

## Installation Steps

Deploying an Enterprise Agent on a Cisco router requires the completion of three steps. These steps are detailed in the sections below:

1. Install the Enterprise Agent on the Cisco router, using one of three available methods (bootflash, direct, via local machine).
2. Configure the container's networking and account information.
3. Verify the agent is running.

For Cisco routers purchased before August 15th, 2021, the Docker image can be installed either directly from the ThousandEyes download servers, or by downloading the container image to a local machine and uploading it to the router via SCP, FTP, TFTP, or USB storage, depending on whether the router has direct Internet access or not.

Routers purchased after August 15th, 2021, can, in addition to the previous methods, install the Enterprise Agent via bootflash.

### Install the Docker Image from Bootflash

If the router was purchased after August 15th, 2021, the router has the ThousandEyes Enterprise Agent available in bootflash.

{% hint style="info" %}
To verify if it is available, use the following command: `Dut1#dir bootflash:/apps`.

{% hint style="info" %}
The filename structure for ThousandEyes agent images is `thousandeyes-enterprise-agent-<ARCH>-<VERSION>.cisco.tar`. The two versions available and their corresponding md5 checksums are:

* thousandeyes-enterprise-agent-x86\_64-5.0.1.cisco.tar
  * md5sum: e8e04b77483d1338d15b4acbb88f9761
* thousandeyes-enterprise-agent-aarch64-5.0.1.cisco.tar
  * md5sum: 773fb8b365ec37fd36d6809c8ce81199

Older routers may have multiple image files installed in the `bootflash:/apps` folder, including 4.x images that use a different file structure. Make sure that the image file you use in the commands below is the newest one.

ThousandEyes also recommends deleting older agent images to free up additional bootflash space.
{% endhint %}
{% endhint %}

1. Run the following command to install via bootflash, replacing `<app-name>` with your application identifier and `<ARCH>-<VERSION>` with the router architecture and the current agent version:

   ```
   #app-hosting install appid <app-name> package bootflash:apps/thousandeyes-enterprise-agent-<ARCH>-<VERSION>.cisco.tar
   ```

### Install the Docker Image to the Router Directly

If the Cisco router has direct internet access, follow the steps below to install the Enterprise Agent:

1. Run the following command to install the image, replacing `<app-name>` with your application identifier and `<ARCH>-<VERSION>` with the router architecture and the current agent version:

   ```
   router#app-hosting install appid <app-name> package https://downloads.thousandeyes.com/enterprise-agent/thousandeyes-enterprise-agent-<ARCH>-<VERSION>.cisco.tar
   ```
2. Your application should now be installed. You can check on it by running the following:

   ```
   router#sh app-hosting list
   App id State
   thousandeyes_enterprise_agent DEPLOYED
   ```

   The output looks like:

   ```
   App id                                   State
   ---------------------------------------------------------
   thousandeyes_enterprise_agent            DEPLOYED
   ```

### Install the Docker Image via a Local Machine

If the Cisco router does not have direct access to the Internet, follow the steps in the sections below to install the Enterprise Agent.

#### Download the Docker Image to a Local Machine

Download the Docker image from the ThousandEyes dashboard and copy it to your Cisco router using SCP, FTP, TFTP, or USB storage.

1. On your local machine, log into the ThousandEyes platform using a login belonging to the account group that will be associated with the appliance.
2. Navigate to **Network & App Synthetics > Agent Settings** and click **Add New Enterprise Agent**; then navigate to **Cisco Application Hosting > Routers**.
3. Download the .tar file matching the router architecture.
4. Use SCP, FTP, TFTP, or USB storage to copy the signed Docker image to the router's flash: directory.
5. Run the following command, replacing `<ARCH>-<VERSION>` with the router architecture and the current agent version:

   ```
   copy scp://<username>@<host>/thousandeyes-enterprise-agent-<ARCH>-<VERSION>.cisco.tar flash:
   ```

{% hint style="info" %}
If the router is behind a http proxy, configure the following to allow the image to be downloaded and installed: `ip http client proxy-server <name> proxy-port <port>`
{% endhint %}

6. Run a checksum (md5) command to verify that the package transfer was successful, replacing `<ARCH>-<VERSION>` with the router architecture and the current agent version. The md5 output should match the latest md5sum. For example, the checksum for version 5.0.1 is `e8e04b77483d1338d15b4acbb88f9761`.

   ```
   router#verify /md5 bootflash:thousandeyes-enterprise-agent-<ARCH>-<VERSION>.cisco.tar
   ```

#### Install the Docker Image from a Local Machine

1. Enable the IOx framework on the router. Enter one configuration command per line, and end with CNTL/Z:

   ```
   router(config)#iox
   router(config)#end
   ```
2. Wait until all the services are running:

   ```
   show iox-service
   IOx Infrastructure Summary:
   IOx service (CAF)          	: Running
   IOx service (HA)           	: Not Supported
   IOx service (IOxman)       	: Running
   IOx service (Sec storage)  	: Not Supported
   Libvirtd 5.5.0             	: Running
   ```
3. Run the installation command, replacing `<app-name>` with your desired app name, `<ARCH>-<VERSION>` with the router architecture and the current agent version, and specifying the location of the image file you want to use. In this example, we use **thousandeyes\_enterprise\_agent**:

   ```
   app-hosting install appid <app-name> package bootflash:thousandeyes-enterprise-agent-<ARCH>-<VERSION>.cisco.tar
   ```
4. If the image is hosted on an HTTPS server, you can run the following command to download the image, replacing `<ARCH>-<VERSION>` with the router architecture and the current agent version:

   ```
   app-hosting install appid <app-name> package https://downloads.thousandeyes.com/enterprise-agent/thousandeyes-enterprise-agent-<ARCH>-<VERSION>.cisco.tar
   ```
5. Your application should now be installed. You can check on it by running the following:

   ```
   sh app-hosting list
   App id State
   thousandeyes_enterprise_agent DEPLOYED
   ```

## Configuration

Docker supports both static IP address assignment and dynamic IP address assignment. You must configure a single virtual network interface card (vNIC) for the appliance using either a management interface or virtual port group interface.

There are two available configuration paths, detailed in the sections below:

### Option One: VirtualPortGroup Interface

1. Configure the VirtualPortGroup interface with a private IP address and use as NAT inside:

   ```
   (config)interface VirtualPortGroup0
   (config)ip address 10.100.152.100 255.255.255.0
   (config)ip nat inside
   ```
2. Configure NAT outside on the physical port interface:

   ```
   (config)interface GigabitEthernet0/0/3
   (config) ip nat outside
   ```
3. Create NAT rule:

   ```
   (config)ip nat inside source list NAT interface GigabitEthernet0/0/3 overload
   (config)ip access-list extended NAT
   (config)10 permit ip 10.100.152.0 0.0.0.255 any
   ```
4. Configure the application, either with a static IP or with DHCP IP:

   a. Configuration with Static IP:

   Use a guest IP address to assign a static IP address. In this example, assign 10.100.152.120/24 from VirtualPortGroup 0 and use Google resolver:

   ```
   (config)#app-hosting appid thousandeyes-enterprise-agent
   (config-app-hosting)#app-vnic gateway0 virtualportgroup 0 guest-interface 0
   (config-app-hosting-gateway0)#guest-ipaddress 10.100.152.120 netmask 255.255.255.0
   (config-app-hosting-gateway0)#app-default-gateway 10.100.152.100 guest-interface 0
   (config-app-hosting-docker)#name-server0 8.8.8.8
   (config-app-hosting)#end
   ```

   Next, set up the required Docker run options to specify account token. If you want to specify a hostname other than the router's name, do this here as well:

   ```
   router(config-app-hosting)#app-resource docker
   router(config-app-hosting-docker)#prepend-pkg-opts
   router(config-app-hosting-docker)#run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN=<Token>"
   router(config-app-hosting-docker)#run-opts 2 "--hostname Cisco-Docker"
   router(config-app-hosting)#start
   router(config-app-hosting)#end
   ```

   b. Configuration with DHCP IP:

   Make sure the DHCP server is running on the VirtualPortGroup interface.

   ```
   (config)#app-hosting appid thousandeyes-enterprise-agent
   (config-app-hosting)#app-vnic gateway0 virtualportgroup 0 guest-interface 0
   (config-app-hosting-docker)#name-server0 8.8.8.8
   (config-app-hosting)#end
   ```

   Next, set up the required Docker run options to specify the account token same as the static IP assignment example above.

   For a full list of the Docker configuration options, see [Docker Agent Configuration Options](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/docker-agent-config-options).
5. Exit three times to completely exit out of config mode.
6. Use **wr mem** to ensure that your configuration changes have persisted across reboots:

   ```
   router#wr mem
   Building configuration...
   [OK]
   ```

### Option Two: Management Interface Configuration

1. Configure the management interface:

   ```
   interface GigabitEthernet0
      vrf forwarding Mgmt-intf
      ip address 10.82.139.212 255.255.255.0
      negotiation auto
   ```
2. Configure the application, either with a static IP or with DHCP IP:

   a. **Configuration with Static IP**:

   1. Use a guest IP address to assign a static IP address. In this example, assign `10.82.139.211/24` from GigabitEthernet 0 and use the Google resolver:

      ```
      (config)#app-hosting appid thousandeyes-enterprise-agent
      (config-app-hosting)#app-vnic management guest-interface 0
      (config-app-hosting-gateway0)#guest-ipaddress 10.82.139.211 netmask 255.255.255.0
      (config-app-hosting-gateway0)#app-default-gateway 10.82.139.212 guest-interface 0
      (config-app-hosting-docker)#name-server0 8.8.8.8
      (config-app-hosting)#end
      ```
   2. Set up the required Docker run options to specify the account token. If you want to specify a hostname other than the router's name, do this here as well:

      ```
      router(config-app-hosting)#app-resource docker
      router(config-app-hosting-docker)#prepend-pkg-opts
      router(config-app-hosting-docker)#run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN=<Token>"
      router(config-app-hosting-docker)#run-opts 2 "--hostname Cisco-Docker"
      router(config-app-hosting)#start
      router(config-app-hosting)#end
      ```

      For a full list of the Docker configuration options, see [Docker Agent Configuration Options](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/docker-agent-config-options).

   b. **Configuration with DHCP IP**:

   1. Make sure the DHCP server is running on the management interface:

      ```
      (config)#app-hosting appid thousandeyes-enterprise-agent
      (config-app-hosting)#app-vnic management guest-interface 0
      (config-app-hosting-docker)#name-server0 8.8.8.8
      (config-app-hosting)#end
      ```
   2. Set up the required Docker run options to specify the account token. If you want to specify a hostname other than the router's name, do this here as well:

      ```
      router(config-app-hosting)#app-resource docker
      router(config-app-hosting-docker)#prepend-pkg-opts
      router(config-app-hosting-docker)#run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN=<Token>"
      router(config-app-hosting-docker)#run-opts 2 "--hostname Cisco-Docker"
      router(config-app-hosting)#start
      router(config-app-hosting)#end
      ```
3. Exit three times to completely exit out of config mode.
4. Use **wr mem** to ensure that your configuration changes have persisted across reboots:

   ```
   router#wr mem
   Building configuration...
   [OK]
   ```

## Verification

With the `(config-app-hosting)#start` command, the Docker container should have been started and should be running. You can verify this through the following options:

```
router# sh app-hosting list
App id                                   State
thousandeyes_enterprise_agent            RUNNING
```

Verify the Docker container’s details:

```
router#sh app-hosting detail appid thousandeyes_enterprise_agent
App id : thousandeyes-enterprise-agent
Owner : iox
State : RUNNING
Application
  Type : docker
  Name : ThousandEyes Enterprise Agent
  Version : 5.0.1
  Description : Perform active synthetic measurements to your business-critical applications. Get started at https://docs.thousandeyes.com/product-documentation/getting-started
  Author : ThousandEyes support@thousandeyes.com
  Path : https://downloads.thousandeyes.com/enterprise-agent/thousandeyes-enterprise-agent-x86_64-5.0.1.cisco.tar
  URL Path : bootflash:./thousandeyes-enterprise-agent-x86_64-5.0.1.cisco.tar
Activated profile name : custom

Resource reservation
  Memory : 500 MB
  Disk : 1 MB
  CPU : 1850 units
  CPU-percent : 9 %
  VCPU : 1

Platform resource profiles
  Profile Name                  CPU(unit) CPU(percent)  Memory(MB)  Disk(MB)
  ---------------------------------------------------------------------------

Attached devices
  Type              Name               Alias
  ---------------------------------------------
  serial/shell     iox_console_shell   serial0
  serial/aux       iox_console_aux     serial1
  serial/syslog    iox_syslog          serial2
  serial/trace     iox_trace           serial3

Network interfaces
   ---------------------------------------
eth0:
   MAC address         : 52:54:dd:e9:9e:9f
   IPv4 address        : 172.29.1.11
   IPv6 address        : ::
   Network name        : VPG0
```

In the ThousandEyes platform, go to **Network & App Synthetics > Agent Settings** and verify the Docker container’s IP address.

## Modify the Docker Container

1. Stop the application:

   ```
   router# app-hosting stop appid thousandeyes_enterprise_agent 
   thousandeyes_enterprise_agent stopped successfully
   Current state is: STOPPED
   ```
2. De-activate the application:

   ```
   router# app-hosting deactivate appid thousandeyes_enterprise_agent 
   thousandeyes_enterprise_agent deactivated successfully
   Current state is: DEPLOYED
   ```
3. Modify the Docker options, and exit three times:

   ```
   router(config)#app-hosting appid thousandeyes_enterprise_agent 
   router(config-app-hosting)#app-resource docker
   router(config-app-hosting-docker)#prepend-pkg-opts
   router(config-app-hosting-docker)#<run-opts command>
   router(config-app-hosting-docker)#exit
   router(config-app-hosting)#exit
   router(config)#exit
   ```
4. Reactivate the application, and confirm that it’s activated:

   ```
   router# app-hosting activate appid thousandeyes_enterprise_agent 
   thousandeyes_enterprise_agent activated successfully
   Current state is: ACTIVATED
   ```

   ```
   router#sh app-hosting list
   App id                                   State
   ---------------------------------------------------------
   thousandeyes-enterprise-agent            DEPLOYED
   ```
5. Start the application, and confirm that it is running:

   ```
   router# app-hosting start appid thousandeyes_enterprise_agent 
   thousandeyes_enterprise_agent started successfully
   Current state is: RUNNING
   ```

## 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 **pool.ntp.org** 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 (pool.ntp.org) be changed to a customer's internal NTP source?**

Yes. For configuration steps, see [NTP Server Configuration on the Cisco Application Hosting Framework Agents (CAF)](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/advanced-configuration-options-for-caf-agents#ntp-server-configuration-on-the-cisco-application-hosting-framework-agents-caf).

**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, replacing `<app-name>` with your application identifier:

```
router#app-hosting connect appid <app-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
```

{% hint style="info" %}
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.
{% endhint %}

For more information on configuration options, see [Docker Agent Config Options](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/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](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/troubleshooting/cli-network-troubleshooting-utilities).

**What are the default trusted default root certificates used by the Enterprise Agent Docker container when communicating with ThousandEyes services?**

* issuer=O = Cisco, CN = Cisco Licensing Root CA
* issuer=O = Cisco, CN = Cisco Basic Assurance Root CA 2099
* issuer=O = Cisco, CN = Cisco ECC Root CA
* issuer=O = Cisco Systems, CN = Cisco Root CA 2048
* issuer=O = Cisco, CN = Cisco Root CA 2099
* issuer=O = Cisco, CN = Cisco Root CA M1
* issuer=O = Cisco, CN = Cisco Root CA M2
* issuer=C = US, O = Cisco Systems, CN = Cisco RXC-R2
* issuer=C = US, O = Amazon, CN = Amazon Root CA 1
* issuer=C = US, O = Amazon, CN = Amazon Root CA 2
* issuer=C = US, O = Amazon, CN = Amazon Root CA 3
* issuer=C = US, O = Amazon, CN = Amazon Root CA 4
* issuer=C = NO, O = Buypass AS-983163327, CN = Buypass Class 2 Root CA
* issuer=C = US, O = DigiCert Inc, OU = [www.digicert.com](http://www.digicert.com), CN = DigiCert Global Root CA
* issuer=C = US, O = Internet Security Research Group, CN = ISRG Root X1
* issuer=C = US, O = IdenTrust, CN = IdenTrust Commercial Root CA 1
* issuer=C = BM, O = QuoVadis Limited, CN = QuoVadis Root CA 2
* issuer=C = US, ST = New Jersey, L = Jersey City, O = The USERTRUST Network, CN = USERTrust ECC Certification Authority
* issuer=C = US, ST = New Jersey, L = Jersey City, O = The USERTRUST Network, CN = USERTrust RSA Certification Authority
* issuer=C = US, O = Google Trust Services LLC, CN = GTS Root R1
* issuer=C = US, O = Google Trust Services LLC, CN = GTS Root R2
* issuer=C = US, O = Google Trust Services LLC, CN = GTS Root R3
* issuer=C = US, O = Google Trust Services LLC, CN = GTS Root R4

**How do I install CA certificates on Cisco devices?**

For CA certificate installation instructions, see [Installing CA Certificates on Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/troubleshooting/installing-ca-certificates-on-enterprise-agents#installing-on-cisco-docker-devices).


# Installing Enterprise Agents on Cisco Switches with the DNA Center

ThousandEyes Enterprise Agents can be installed on Cisco devices using the Cisco DNA Center. This article provides a video walkthrough of the installation and configuration process, as well as some troubleshooting solutions.

{% hint style="info" %}
As a part of container package best practices, we recommend updating your container regularly.
{% endhint %}

## Supported Devices

For a full list of supported devices, see the [Support Matrix](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices#support-matrix).

## Prerequisites

Before following the video instructions, users should have the following configured/set up:

* Login credentials to the DNA Center with either **Network Admin** or **Super Admin** permissions.
* A VLAN for the Enterprise Agent to use.
* An IP address with a routable subnet with permission to connect to the ThousandEyes cloud, allowing outgoing HTTPS connections directly or through a proxy server.
* Ensure the target devices are reachable and managed by the DNA Center. For more information, see the [Cisco DNA Center Documentation](https://www.cisco.com/c/en/us/products/collateral/switches/catalyst-9400-series-switches/guide-c07-2431113.html?dtid=osscdc000283#CiscoCatalystCenter).

  ![](/files/M6HJgLL1kkpmRPjILMur)

{% hint style="warning" %}
A security advisory has been published, relating to the HTTP server component in IOS-XE. This advisory can be found here: [Cisco Security Advisories](https://sec.cloudapps.cisco.com/security/center/content/CiscoSecurityAdvisory/cisco-sa-iosxe-webui-privesc-j22SaA4z).

While following the recommended steps in the advisory, and disabling HTTP server feature, does not directly impact the ability to run a ThousandEyes Enterprise Agent on a Cisco device, we recommend that customers who intend to use DNAC or other external tooling to manage their Cisco network devices follow the instructions within the security advisory to utilize an ACL to only allow trusted devices to access the HTTP server component.
{% endhint %}

## Installation Video

The video walkthrough is available here: [ThousandEyes Resources](https://www.thousandeyes.com/resources/installing-thousandeyes-enterprise-agent-cisco-catalyst-9000-tutorial).

## Troubleshooting

### Incorrect file download from Cisco DNA Center versions 2.2.2.x and 2.2.3.x

There is an existing bug with Cisco DNA Center versions 2.2.2.x and 2.2.3.x that causes an unsupported version of the ThousandEyes Enterprise Agent to be downloaded. The summary and workaround are listed below; more details can be found here: [Cisco Issue Tracker](https://bst.cloudapps.cisco.com/bugsearch/bug/CSCwb74636).

#### Summary

When running Cisco DNA Center versions 2.2.2.x or 2.2.3.x, the hyperlink to download the **tar.gz** file automatically redirects to ThousandEyes Enterprise Agent version 4.2.2. This version is not supported on Cisco DNA Center versions earlier than 2.3.3.x, and will cause an error due to the changes in the **controller.yaml** file.

#### Workaround

To workaround this issue, ThousandEyes Enterprise Agent version 4.1.0 can be downloaded and imported instead. This version is still supported under the correct schema:.

### Deploy failed (ERR\_AH\_1000): 400 Client Error: Bad Request ("Duplicate mount point: /var/tmp/te-agent")

There is an existing bug that caused users trying to deploy the ThousandEyes Enterprise Agent with Cisco DNA Center 2.3.2.x to receive the failure message `Deploy failed (ERR_AH_1000): 400 Client Error: Bad Request ("Duplicate mount point: /var/tmp/te-agent")`. A workaround is listed below; more details can be found here: [Cisco Issue Tracker](https://bst.cloudapps.cisco.com/bugsearch/bug/CSCvz84369).

#### Workaround

Navigate to the ThousandEyes app in the Cisco DNA Center Application Hosting page. In the docker runtime options, remove the following line from the configuration:

`--mount type=tmpfs,destination=/var/tmp/te-agent,tmpfs-size=340m`

Save the changes, and the setup should then work as expected.


# Docker Agent Configuration Options

You can configure the Enterprise Agent by setting environment variables, such as **run-opts 1**, on your Cisco Catalyst switch as follows:

```
    Device(config)# app-hosting appid thousandeyes_enterprise_agent
    Device(config-app-hosting)# app-resource docker
    Device(config-app-hosting-docker)# prepend-pkg-opts
    Device(config-app-hosting-docker)# run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN"
    Device(config-app-hosting-docker)# run-opts 2 "--hostname DESIRED_AGENT_HOSTNAME"
    Device(config-app-hosting-docker)# run-opts 3 "-e TEAGENT_PROXY_TYPE=STATIC"
    Device(config-app-hosting-docker)# run-opts 4 "-e TEAGENT_PROXY_LOCATION=proxy.something.other:80"
    Device(config-app-hosting-docker)# exit
    Device(config-app-hosting)# exit
    Device(config)# exit
```

This article lists the available configuration options for these **run-opts** variables.

* `APT_PROXY_LOCATION`

  When `PROXY_APT` is set, the hostname or hostname:port to use for the apt proxy. Default: Not set.
* `APT_PROXY_PASS`

  When `PROXY_APT` is set, the password to use for the apt proxy. Default: Not set.
* `APT_PROXY_USER`

  When `PROXY_APT` is set, the username to use for the apt proxy. Default: Not set.
* HOSTNAME

The agent hostname you would like to assign. Default: the hostname of the switch.

* `PROXY_APT`

  Specifies whether a proxy is necessary to reach apt repositories when `PROXY_TYPE` is `PAC`. Setting this to anything enables proxying for apt. Default: not set.

Note: When `PROXY_TYPE` is `STATIC`, apt will be configured to use the proxy defined at `TEAGENT_PROXY_LOCATION` with the authentication defined by `TEAGENT_PROXY_USER` and `TEAGENT_PROXY_PASS`. Also note that apt supports basic proxy authentication only.

* `TEAGENT_ACCOUNT_TOKEN`

  The account group token for registration. This option must be set.
* `TEAGENT_AUTO_UPDATES`

  Specifies whether the agent will perform automatic self-updates of ThousandEyes packages. Valid values are 0 and 1. Default: 1.

  Note: This setting does not affect base OS-level packages; only ThousandEyes software.
* `TEAGENT_KERBEROS_RDNS`

  Specifies whether reverse DNS lookups should be performed and checked for Kerberos hostnames. Valid values are 0 and 1. Default: 1.
* `TEAGENT_KERBEROS_WHITELIST`

  Not needed for IOS XE 17.3.3.
* `TEAGENT_KDC_HOST`

  When using `KERBEROS` proxy authentication, the hostname where the KDC can be reached. Default: Not set.
* `TEAGENT_KDC_PASS`

  When using `KERBEROS` proxy authentication, the password to use for communication with the KDC. Default: Not set.
* `TEAGENT_KDC_PORT`

  When using `KERBEROS` proxy authentication, the port to use for communication with the KDC. Default: 88
* `TEAGENT_KDC_REALM`

  When using `KERBEROS` proxy authentication, the realm to use for communication with the KDC. Default: Not set.
* `TEAGENT_KDC_USER`

  When using `KERBEROS` proxy authentication, the username to use for communication with the KDC. Default: Not set.
* `TEAGENT_PROXY_AUTH_TYPE`

  The type of authentication to use when connecting to the configured proxy. Default: Not set.

  * Not set: Do not use authentication.
  * `BASIC`: Use HTTP BASIC authentication. `TEAGENT_PROXY_USER` and `TEAGENT_PROXY_PASS` must be set.
  * `NTLM`: Use HTTP NTLM authentication. `TEAGENT_PROXY_USER` and `TEAGENT_PROXY_PASS` must be set.
  * `KERBEROS`: Use Kerberos authentication. `TEAGENT_KDC_USER`, `TEAGENT_KDC_PASS`, `TEAGENT_KDC_REALM`, `TEAGENT_KDC_HOST`, and `TEAGENT_KDC_PORT` must be set.
* `TEAGENT_PROXY_BYPASS_LIST`

  When using a `STATIC` proxy, a list representing the endpoints that should *not* require proxy use. Default: Not set.

  The list should be separated by semicolons and each entry should be one of the following:

  * A specific hostname or IP address. eg, `foo.somedomain.com` or `128.1.10.24`. In the case of an IP address, the proxy will be bypassed only if the IP is present in the URL itself. This will *not* apply to an IP address used as a result of DNS resolution on a hostname.
  * A wildcard hostname starting with a `*`. eg, `*.somedomain.com`. A proxy will not be used for any request targeting subdomains of `somedomain.com`. Note that requests to `somedomain.com` itself *will* still use the proxy.
  * A network prefix. eg, `128.1.0.0/24`. If the requested URL is for a literal IP address, bypass the proxy if the IP lies within this network prefix.
* `TEAGENT_PROXY_LOCATION`

  Proxy location. Default: Not set.

  * For `STATIC` proxies, the hostname:port where the proxy is located (eg, `proxy.thousandeyes.com:3128`).
  * For `PAC` proxies, a URL where the PAC file can be downloaded (eg, `https://somewhere.com/pac`).
  * Should not be set if `TEAGENT_PROXY_TYPE` is `DIRECT`.
* `TEAGENT_PROXY_PASS`

  The password for proxy authentication. Default: Not set.
* `TEAGENT_PROXY_TYPE`

  The type of proxy to use for communication with the ThousandEyes platform. Default: `DIRECT`.

  * `DIRECT`: Do not use a proxy, go directly to the destination.
  * `STATIC`: Use a statically configured proxy location.
  * `PAC`: Use a PAC file to determine the proxy’s location
* `TEAGENT_PROXY_USER`

  The username for proxy authentication. Default: Not set.


# Enterprise Agent Configuration

After you have deployed a ThousandEyes Enterprise Agent, you may need to configure its settings or other aspects of its environment. This section contains articles detailing how to configure Enterprise Agents.


# Password Reset on the Virtual Appliance

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

The ThousandEyes Virtual Appliance can be configured through a web interface which is available at **http\://\<IP\_address\_of–Virtual\_Appliance>**. The web interface requires a username and password. The default username and password are:

**Username**: admin\
**Password**: welcome

The Virtual Appliance installation process will require the password to be changed:

![Figure 1: Change Password](/files/-M62_NYt6zcyqSI-2Xta)

## Resetting the Password from the App

If the agent is online in the ThousandEyes app, the easiest way to force a password reset is from the **Enterprise Agents** tab of the **Network & App Synthetics > Agent Settings** page:

![](/files/-M62_NYkNsRdD9WzjAF1)

After expanding the agent's row, a **Reset Appliance Password** link appears. Clicking the link will reset the default username and password on the Appliance.

The final step is to log in to the Virtual Appliance's web management page at **http\://\<IP\_address\_of–Virtual\_Appliance>** using the default credentials. In the **Access** tab, you will be required to change the password (see Figure 1).

## Resetting the Password from the Hypervisor

If you can't log in to the Virtual Appliance's web management page, the password can be reset using the Virtual Appliance's console. The console provides a text-driven menu for basic administrative tasks. The console window is a tty device which can be accessed from the hypervisor that is hosting the Virtual Appliance.

![](/files/-M62_NYzlqKA0PFZg50M)

In the console, press the **R** key to reset the password to the default value.

Next, navigate to the Virtual Appliance's web management page at **http\://\<IP\_address\_of–Virtual\_Appliance>** and log in using the default credentials. Upon the initial login, you will be required to change the password (see Figure 1).

NOTE: If the **Current Password** field has been auto-populated, then your browser's password manager has filled the field with a value that may or may not be correct. If you receive an error that the auto-populated password is incorrect, then delete the contents of the **Current Password** and manually enter "welcome", in order to change the password. We strongly recommend disabling password completing for the Virtual Appliance's URLs.


# Installing CA Certificates on Enterprise Agents

Enterprise Agents which perform Web Layer tests to targets protected by SSL/TLS (a target URL beginning with https\://, ftps\://, or ftp\:// when using implicit-mode SSL/TLS) must validate the SSL server digital certificate and any intermediate certificates returned by the server or fetched by the client. Additionally, Enterprise Agents perform configuration download and data upload to ThousandEyes servers using TLS. Certificate validation requires that the sequence of certificates “chain” via digital signature back to the trusted root certification authority (CA) certificate that signed the previous certificate in the chain. As with most browsers and operating systems, ThousandEyes Enterprise Agents are pre-loaded with the standard X.509 CA certificate store of root CA certificates, which is provided by the [Mozilla NSS project](https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/).

In some environments, the certificate(s) returned by the server do not chain back to a CA certificate in the standard certificate store, causing Web Layer tests to produce certificate errors and/or the administrative communication to ThousandEyes to fail. To avoid the errors, customers can add any needed certificates to an Enterprise Agent’s certificate store. The steps to add certificates vary, depending on the type of Enterprise Agent.

Adding root CA certificates cannot be performed on Cloud Agents, due to the shared nature of Cloud Agents. Endpoint Agents are installed on standard operating systems which the customer controls, including control of the certificate stores.

## When to add certificates to an Enterprise Agent

When any Web Layer test (HTTP Server test, Page Load test, Transaction test or FTP Server test) or administrative communication from the Agent to ThousandEyes produces a certificate error, review the following scenarios to determine whether a root CA certificate must be added to the Enterprise Agent’s certificate store.

* **Certificates are issued by a private root CA certificate (internal PKI)**

Organizations which run their own public key infrastructure (PKI) will issue their own SSL server certificates, intermediate certificates (if any), and root CA certificate(s) which will not be included in the standard Mozilla root certificate store. The root CA certificate that issued certificates on servers that are the targets of ThousandEyes tests must be added to the Enterprise Agent.

* **Decrypting proxy server**

If an Enterprise Agent is explicitly configured to use a proxy or if an Agent's web traffic is captured by a transparent proxy (a proxy that does not require configuration of the client) and the proxy performs SSL/TLS decryption, then the proxy's signing certificate(s) must be added to the Enterprise Agent. Proxy servers which decrypt and inspect data carried by SSL/TLS use a signing certificate to rewrite server certificates. Typically, the proxy signing certificate is not issued by one of the certificates in the standard certificate store. Often, the proxy software generates this certificate. The decrypting proxy scenario affects both ThousandEyes Web Layer tests and Agent communication to ThousandEyes.

* **Self-signed SSL server certificate**

  A self-signed SSL server certificate will not chain back to a root CA certificate in the Enterprise Agent's standard certificate store. If correctly created, a self-signed certificate can be added to the Enterprise Agent's certificate store to eliminate certificate errors when the Agent performs tests to the server with the self-signed certificate.

  Additionally, if the target of the test does have certificates issued by a Certificate Authority whose root certificate is in the Agent's certificate store, but the target server does not return all needed intermediate certificates, and the customer cannot add the missing certificates on the server, then the intermediate certificate(s) can be added to the Enterprise Agent’s certificate store to create the “trust anchor” other than the root CA certificate. However, the customer should take great care in ensuring the veracity of any intermediate certificates, and understand and accept the impact the new trust anchor could have on other tests or aspects of the Agent operation, either in the present or in the future. ThousandEyes does not recommend adding intermediate certificates to an Enterprise Agent's certificate store.

### Confirm a CA Certificate is Needed for Proxy Environments

If your agent registration fails, and your Enterprise Agent is installed behind a proxy, you can check the agent logs to confirm that the proxy is the cause of the failure, and that a CA certificate is required:

```
root@example:/home# tail /var/log/agent/te-agent.log
2022-06-30 03:35:52.211 INFO  [9997ff00] [te.agent.ClusterMasterAdapter] {} Attempting to get agent id from https://sc1.thousandeyes.com
2022-06-30 03:35:52.242 ERROR [9997ff00] [te.agent.status] {} Error calling createAgent: Curl error - Peer certificate cannot be authenticated with given CA certificates
```

You can also use the **curl** command, replacing the **proxy** and **port** variables:

```
# curl -v https://sc1.thousandeyes.com -x <proxy>:<port>
```

If there is no certificate, you will see output similar to the example below:

```
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
* TLSv1.3 (IN), TLS handshake, Certificate (11):
* TLSv1.3 (OUT), TLS alert, unknown CA (560):
* SSL certificate problem: unable to get local issuer certificate
```

The expected response is “404 Not Found”, validating that while the agent still needs a CA certificate, it does have access to the Internet through proxy.

## Converting certificates into PEM format

To add a CA certificate to an Enterprise Agent, the certificate file must be in [PEM format](https://en.wikipedia.org/wiki/X.509#Certificate_filename_extensions). This format can easily be recognized by viewing the file:

```
-----BEGIN CERTIFICATE-----
...
... (certificate content, base64 encoded)
...
-----END CERTIFICATE-----
```

If your CA certificate is in a format other than PEM format, either use one of the free online certificate converters ([link #1](https://www.sslshopper.com/ssl-converter.html), [link #2](https://www.sslchecker.com/ssl_converter) or [link #3](https://www.thesslstore.com/ssltools/ssl-converter.php)), or use the commands below to convert your CA certificate into PEM format with the `openssl` command line utility.

Convert a DER file (.crt, .cer or .der) to PEM format:

```
openssl x509 -inform der -in infile -out outfile.pem
```

Convert a PKCS#12 file (.pfx or .p12) to PEM format:

```
openssl pkcs12 -in infile -out outfile.pem -nodes
```

## Installing on Virtual Appliances

Log into the Virtual Appliance's web management console, and click on the Network tab:

![](/files/-M5xtOmug-e50O0lviP9)

In the CA Certificate section, either paste the CA certificate into the **Add CA Certificate** field or browse to your PEM-formatted certificate file:

![](/files/-M5xtOmx9f2oyyVfq-G6)

If pasting, ensure that whole certificate is pasted into the field, including the "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" markers at the beginning and end of the certificate.

Multiple CA certificates may be installed by copying and pasting each certificate, concatenating the certificates in the **Add CA Certificate** field:

![](/files/-M5xtOn-oQ5PZPgtjPo_)

Click the **Save** button at the bottom of the page to complete the operation.

## Installing on supported Linux Distributions

When installing CA certificates on supported Linux distributions with the Enterprise Agent, CA certificates must be installed in two locations:

1. The system's CA certificate store
2. The NSSDB certificate store in the .pki/nssdb sub-directory of BrowserBot's home directory /var/lib/te-browserbot

   All commands should be executed as root. If logging into the system as a non-privileged user, begin each command with sudo.

The instructions below are provided in two sections for the two sets of supported Linux distributions: 1) Ubuntu and 2) Red Hat Enterprise Linux, CentOS and Oracle Linux. These instructions use the example certfile filename **MY-CA-CERT.pem**.

### Ubuntu

Install the required packages for managing CA certificates:

```
apt-get install ca-certificates libnss3-tools
```

Copy the certfile file (in PEM format; see above for conversion information) into the **/usr/share/ca-certificates** directory of the Enterprise Agent:

```
cp MY-CA-CERT.pem /usr/share/ca-certificates/
```

Open the **/etc/ca-certificates.conf** file in a text editor:

```
nano /etc/ca-certificates.conf
```

Append a line containing only the certfile filename to the end of the file:

```
#...
#...(existing certificates here)
#...
MY-CA-CERT.pem
```

{% hint style="info" %}
Multiple certificate files can be added using multiple lines.
{% endhint %}

Update the system certificate store using the `update-ca-certificates` command, as shown below, with successful output:

```
root@my-ubuntu-agent:~# update-ca-certificates
Updating certificates in /etc/ssl/certs... 1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...

Adding debian:MY-CA-CERT.pem

done.
done.
root@my-ubuntu-agent:~#
```

The system CA certificate store now contains your CA certificate(s).

For BrowserBot, first create the directory that will contain the certificate store:

```
mkdir -p /var/lib/te-browserbot/.pki/nssdb
```

Initialize the certificate store in directory created above:

```
certutil -N --empty-password -d sql:/var/lib/te-browserbot/.pki/nssdb
```

Add the CA certificate into the newly created certificate store:

```
certutil \
  -d sql:/var/lib/te-browserbot/.pki/nssdb/ \
  -A \
  -t "C" \
  -n "MY-CA-CERT" \
  -i /usr/share/ca-certificates/MY-CA-CERT.pem
```

Change both the owner and the group of all newly created files and directories to browserbot:

```
chown -R browserbot.browserbot /var/lib/te-browserbot/.pki
```

Restart the te-browserbot service:

```
systemctl restart te-browserbot   # Ubuntu 16.04
restart te-browserbot             # Ubuntu 14.04
service te-browserbot restart     # Ubuntu 16.04 and/or 14.04
```

### Red Hat Enterprise Linux, CentOS and Oracle Linux

Install the required packages for managing CA certificates:

```
yum install ca-certificates nss-tools
```

Copy the certfile file (in PEM format; see above for conversion information) into the **/etc/pki/ca-trust/source/anchors/** directory of the Enterprise Agent:

```
cp MY-CA-CERT.pem /etc/pki/ca-trust/source/anchors/
```

Update the system certificate store using the **update-ca-trust** command:

```
update-ca-trust extract
```

The system CA certificate store now contains your the CA certificate.

For BrowserBot, first create the directory that will contain the certificate store:

```
mkdir -p /var/lib/te-browserbot/.pki/nssdb
```

Initialize the certificate store in the directory:

```
certutil -N --empty-password -d sql:/var/lib/te-browserbot/.pki/nssdb
```

Add the CA certificate to the newly created certificate store:

```
certutil \
  -d sql:/var/lib/te-browserbot/.pki/nssdb/ \
  -A \
  -t "C" \
  -n "certificate name" \
  -i /etc/pki/ca-trust/source/anchors/MY-CA-CERT.pem
```

On RHEL/CentOS 7 only, change both the owner and the group of all newly created files and directories to browserbot. On RHEL/CentOS 6 this step must be skipped:

```
chown -R browserbot.browserbot /var/lib/te-browserbot/.pki   # RHEL / CentOS 7 only!
```

Restart the te-browserbot service:

```
systemctl restart te-browserbot   # RHEL / CentOS 7
restart te-browserbot             # RHEL / CentOS 6
```

## Installing on Docker

The Enterprise Agent Docker image has built-in support for CA certificates for both the Enterprise Agent and BrowserBot NSSDB store. On container startup, the supplied CA certificates will be installed in the container to be used for all tests, as well as communications with the ThousandEyes platform.

To use CA certificates in your Docker Enterprise Agent, create a directory on the Docker host that contains your CA certificate files. Add that directory to your Docker container run script as a volume mount pointing to `/var/lib/te-agent/ca-certificates`:

```
-v '/host/path/to/ca/certificates/':/var/lib/te-agent/ca-certificates
```

Restart the container for the certificate loading to occur.

{% hint style="info" %}
Certificates are only processed on container startup. If any modifications are made to your certificate store, the container must be restarted.
{% endhint %}

{% hint style="info" %}
Certificates in the volume mount must be regular files in PEG format and not in a subdirectory.
{% endhint %}

To verify certificate installation, check the Docker logs for your container:

```
Refreshing certificate store...
Installed certificate: /usr/local/share/ca-certificates/MY-CA-CERT.pem
```

## Installing on Cisco Application Hosting Containers

{% hint style="info" %}
Starting with Cisco Application Hosting 5.0, Cisco Enterprise Agents will use **apk** instead of **apt** for auto-updates
{% endhint %}

{% hint style="info" %}
The instructions in this section assume the PEM format certificate has been created and copied onto the Cisco device, and that the Enterprise Agent container image version is 5.1.1 or higher.

Refer to the [Converting Certificates into PEM Format](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/troubleshooting/installing-ca-certificates-on-enterprise-agents#converting-certificates-into-pem-format) section of this document to create the PEM format certificate.
{% endhint %}

To install a CA certificate in a container with a proxy configuration, add the proxy information as run options, as shown in the example below. If you are using a transparent SSL-decrypting proxy, no proxy configuration is needed.

{% hint style="warning" %}
Ensure the configuration includes the SSL decrypting proxy location before running the application container
{% endhint %}

1. For new Enterprise Agents, continue to step two. For existing agents, ensure you stop and deactivate the application before continuing. For more information on how to stop/deactivate the container, see the [Lifecycle of an Application](https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/176/b_176_programmability_cg/m_176_prog_app_hosting.html#id_74345) section of the Cisco documentation.
2. Configure the proxy for the container:

   ```
   Device(config)#app-hosting appid example
   Device(config-app-hosting)# app-resource docker
   Device(config-app-hosting-docker)# prepend-pkg-opts
   Device(config-app-hosting-docker)# run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN=<token>"
   Device(config-app-hosting-docker)# run-opts 2 "--hostname $(SYSTEM_NAME)"
   Device(config-app-hosting-docker)# run-opts 3 "-e TEAGENT_PROXY_TYPE=STATIC"
   Device(config-app-hosting-docker)# run-opts 4 "-e TEAGENT_PROXY_LOCATION=<proxy-ssldecrypting.com>:3128"
   Device(config-app-hosting)# end
   ```
3. Activate the container, and verify it is in the **ACTIVATED** state:

   ```
   Device#app-hosting activate appid example
   Device#show app-hosting list
   App id                               	      State
   ---------------------------------------------------------
   example                                  	ACTIVATED
   ```
4. Copy the certificate into the container. You must use the `ca-certificates` directory shown in the example below, as an initialization script in the container looks for certificates in that location:

   ```
   Device#app-hosting data appid example copy bootflash:MY-CA-CERT.crt ca-certificates/MY-CA-CERT.crt
   ```
5. Start the container and ensure it is in the **RUNNING** state:

   ```
   Device#app-hosting start appid example
   Device#show app-hosting list
   App id                               	      State
   ---------------------------------------------------------
   example                                  	RUNNING
   ```

The CA certificate is now installed for use by the agent, including for tests that use BrowserBot. Each time the container is restarted, a container initialization script will look for a certificate file in the `ca-certificates` directory shown in the example above.

{% hint style="warning" %}
Do not delete the certificate file unless it is no longer needed.
{% endhint %}

If the certificate needs to be replaced at some point, follow the steps below.

1. Stop the container.

   ```
   Device#app-hosting stop appid example
   ```
2. Delete the existing certificate file from the container.

   ```
   Device#app-hosting data appid example delete ca-certificates/MY-CA-CERT.crt
   ```
3. Copy the new certificate into the container. You must use the `ca-certificates` directory shown in the example below, as an initialization script in the container looks for certificates in that location:

   ```
   Device#app-hosting data appid example copy bootflash:MY-CA-CERT.crt ca-certificates/MY-CA-CERT.crt
   ```
4. Start the container and ensure it is in the **RUNNING** state:

   ```
   Device#app-hosting start appid example
   Device#show app-hosting list
   App id                               	      State
   ---------------------------------------------------------
   example                                  	RUNNING
   ```

{% hint style="info" %}
If the container is uninstalled, the certificate in that container will be deleted. If the certificate is needed when a new container is installed, copy it into the new container using the instructions above.
{% endhint %}


# Advanced Configuration Options for CAF Agents

This article covers the main advanced configuration options available when running Enterprise Agents on Cisco Application Hosting Framework (CAF) based devices.

The article assumes that you are following the relevant installation instructions for your device, available under the [Cisco Devices](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/cisco-devices) landing page.

{% hint style="warning" %}
These advanced configuration options are only available for CAF Enterprise Agent version 5.1.1 and later. Please ensure that your agent is upgraded to the latest version before adding these advanced configuration options.

Upgrade instructions can be found here: [Upgrade Cisco Application Hosting Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents#cisco-application-hosting).
{% endhint %}

## NTP Server Configuration on the Cisco Application Hosting Framework Agents (CAF)

Enterprise Agents running inside a Cisco application hosting container use the clock provided by the Cisco device's kernel. This system clock should be kept in sync using an appropriate time protocol configured on the network operating system, as the agent does not adjust the clock on the Cisco device.

The agent makes periodic NTP requests to determine the clock offset and adjust the test measurements timestamps as needed. These requests are sent to `pool.ntp.org` by default. This can be changed by providing the agent with a list of NTP servers via an environment variable during the configuration stage. An initialization script within the application container will then set up the **/etc/ntp.conf** file with the provided NTP servers, and the agent will use the configured NTP servers upon startup.

To configure the NTP server list:

1. For new Enterprise Agents, continue to step two. For existing agents, ensure you stop and deactivate the application before continuing. For more information on how to stop/deactivate the container, see the [Lifecycle of an Application](https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/176/b_176_programmability_cg/m_176_prog_app_hosting.html#id_74345) section of the Cisco documentation.
2. In config mode, enter into the submode for the application-hosting container used for the ThousandEyes agent, and use the `run-opts` option to configure a semi-colon (;) separated list of NTP server pools, names, or addresses. An example is shown below.

   ```
   Device(config)#app-hosting appid example
   Device(config-app-hosting)# app-resource docker
   Device(config-app-hosting-docker)# prepend-pkg-opts
   Device(config-app-hosting-docker)# run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN=<token>"
   Device(config-app-hosting-docker)# run-opts 2 "--hostname $(SYSTEM_NAME)"
   Device(config-app-hosting-docker)# run-opts 3 "-e TEAGENT_NTP_LIST=<ntp1>;<ntp2>;<ntp3>"
   Device(config-app-hosting)# end
   ```
3. Activate the container, and verify it is in the **ACTIVATED** state:

   ```
   Device#app-hosting activate appid example
   Device#show app-hosting list
   App id                               	      State
   ---------------------------------------------------------
   example                                  	ACTIVATED
   ```
4. Start the container and ensure it is in the **RUNNING** state:

   ```
   Device#app-hosting start appid example
   Device#show app-hosting list
   App id                               	      State
   ---------------------------------------------------------
   example                                  	RUNNING
   ```

For more information on configuring the clock on Cisco devices, see the following reference documentation:

* [Network Time Protocol for Cisco IOS XE 17.x](https://www.cisco.com/c/en/us/td/docs/routers/ios/config/17-x/syst-mgmt/b-system-management/m_bsm-time-calendar-set.html)
* [Cisco Nexus 9000 Series NX-OS Fundamentals Configuration Guide](https://www.cisco.com/c/en/us/td/docs/dcn/nx-os/nexus9000/105x/configuration/fundamentals/cisco-nexus-9000-series-nx-os-fundamentals-configuration-guide-release-105x/m-basic-device-management.html)

## CA Certificates for Cisco Application Hosting Framework (CAF) Agents

For detailed instructions on installing a CA certificate on Cisco devices that support the Cisco application hosting framework (CAF), see [Installing CA Certificates on Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/installing-ca-certificates-on-enterprise-agents#installing-on-cisco-devices-supporting-the-cisco-application-hosting-framework-caf).

## Security Mode for Cisco Application Hosting Framework (CAF) Agents

Enterprise Agents running in application hosting containers can operate in a FIPS compliant mode that restricts the set of protocols used when interacting with the ThousandEyes platform.

{% hint style="info" %}
This does not prevent the Enterprise Agents from performing synthetic tests to servers using less secure protocols.
{% endhint %}

To configure the Enterprise Agent to operate in FIPS mode:

1. For new Enterprise Agents, continue to step two. For existing agents, ensure you stop and deactivate the application before continuing. For more information on how to stop/deactivate the container, see the [Lifecycle of an Application](https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/176/b_176_programmability_cg/m_176_prog_app_hosting.html#id_74345) section of the Cisco documentation.
2. Set the `TEAGENT_SECURITY_MODE` environment variable to FIPS as shown in the example below:

   ```
   Device(config)#app-hosting appid example
   Device(config-app-hosting)# app-resource docker
   Device(config-app-hosting-docker)# prepend-pkg-opts
   Device(config-app-hosting-docker)# run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN=<token>"
   Device(config-app-hosting-docker)# run-opts 2 "--hostname $(SYSTEM_NAME)"
   Device(config-app-hosting-docker)# run-opts 3 "-e TEAGENT_SECURITY_MODE=FIPS"
   Device(config-app-hosting)# end
   ```
3. Activate the container, and verify it is in the **ACTIVATED** state:

   ```
   Device#app-hosting activate appid example
   Device#show app-hosting list
   App id                               	      State
   ---------------------------------------------------------
   example                                  	ACTIVATED
   ```
4. Start the container and ensure it is in the **RUNNING** state:

   ```
   Device#app-hosting start appid example
   Device#show app-hosting list
   App id                               	      State
   ---------------------------------------------------------
   example                                  	RUNNING
   ```

An initialization script within the application container will set up the **security-mode** parameter in the agent configuration file. When the agent starts, it will be operating in FIPS mode.

To take the agent out of FIPS mode:

1. Stop and deactivate the application.
2. Remove the security mode environment variable by using the `no run-opts` command, followed by the index number for that environment variable. This example uses index number 3, as seen in the setup instructions above. The option text is not required when using the `no run-opts` command is used:

   ```
   Device(config)#app-hosting appid example
   Device(config-app-hosting)# app-resource docker
   Device(config-app-hosting-docker)# no run-opts 3
   Device(config-app-hosting)# end
   ```
3. Activate the container, and verify it is in the **ACTIVATED** state:

   ```
   Device#app-hosting activate appid example
   Device#show app-hosting list
   App id                               	      State
   ---------------------------------------------------------
   example                                  	ACTIVATED
   ```
4. Start the container and ensure it is in the **RUNNING** state:

   ```
   Device#app-hosting start appid example
   Device#show app-hosting list
   App id                               	      State
   ---------------------------------------------------------
   example                                  	RUNNING
   ```

When the agent starts in the container, it will now operate in default mode.

{% hint style="tip" %} You can also set the agent to operate in default mode by configuring the environment variable to `TEAGENT_SECURITY_MODE=DEFAULT`.


# Configuring rDNS Lookups for Enterprise Agents

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

A reverse DNS lookup or resolution (rDNS) queries the Domain Name System (DNS) to determine the domain name associated with an IP address. This is the opposite of a standard DNS lookup, which determines the IP address associated with a domain name.

ThousandEyes Enterprise Agents perform rDNS lookups for [RFC 1918](https://datatracker.ietf.org/doc/html/rfc1918) addresses by default. The agent performs lookups for each hop in the path, until it encounters a non-RFC 1918 address, or one that is not in the configured rDNS ranges.

This article provides the steps to extend rDNS lookups by the agent for public IP addresses.

## Prerequisites

* One or more ThousandEyes Enterprise Agents or clusters.

## Configuration

To configure the agent's reverse DNS behavior:

1. In the ThousandEyes web app:
   * For Enterprise Agents, navigate to **Network & App Synthetics > Agent Settings > Enterprise Agents > Agents**.
   * For clusters, navigate to **Network & App Synthetics > Agent Settings > Enterprise Agents > Clusters**.
2. Click the Enterprise Agent or cluster you wish to configure to open the **Edit Configuration** panel.
3. Open the **Advanced Settings** tab.
4. In the **Reverse DNS** section, add the public IP ranges that should be used for the rDNS lookups.

![](/files/g6EHdZIZbCULb9LoW0fE)

5. After adding the ranges, click **Save Changes**.

To configure multiple Enterprise Agents at once:

1. Navigate to **Cloud and Enterprise Agents > Agent Settings > Enterprise Agents > Agents**.
2. Select the checkbox beside each desired Enterprise Agent, or the checkbox beside **Agent Name** to select all.
3. From the bottom configuration options panel, open the **Edit** menu and select **Edit Reverse DNS**.

![](/files/ukVAqZaMFPh1Sgdx4a2B)

4. In the **Reverse DNS** side panel, configure the public IP ranges, and click **Save Changes**.

![](/files/pk5IduZyCpK9Nk7pe7gK)

Once configured, the domain name for each hop will be displayed in the Path Visualization. Hover the cursor over the node to see that node's details:

![](/files/SFqQJJseR8lIEL4ngnFy)


# Connecting to the ThousandEyes Virtual Appliance Using SSH (Mac/Linux)

In order to connect to the ThousandEyes VA, you first need to configure the Virtual Appliance with an SSH public key.

## Generate an SSH Key

### Step 1: Check for SSH Keys

First, we need to check for existing ssh keys on your computer. Open a terminal session and run:

```
cat ~/.ssh/id_rsa.pub
```

If it says "No such file or directory" go to **step 2**. Otherwise, you already have an existing keypair, and you can skip to **step 3**.

### Step 2: Generate a New SSH Key

To generate a new SSH key, enter the code below. We want the default settings so when asked to enter a file in which to save the key, just press enter.

```
ssh-keygen -t rsa -C "your_email@example.com"
Generating public/private rsa key pair.
Enter file in which to save the key (/your/home/dir/xxxx/.ssh/id_rsa): [Press enter]
```

Now you need to enter a passphrase.

```
Enter passphrase (empty for no passphrase): [Type a passphrase]
Enter same passphrase again: [Type passphrase again]
```

Which should give you something like this:

```
Your identification has been saved in /your/home/dir/.ssh/id_rsa.
Your public key has been saved in /your/home/dir/.ssh/id_rsa.pub.
The key fingerprint is:
01:0f:f4:3b:ca:85:d6:17:a1:7d:f0:68:9d:f0:a2:db your_email@example.com
```

### Step 3: Add Your SSH Key to the VA

Copy the contents of the public key to your clipboard. The following command can be used on Mac OS X to do so:

```
pbcopy < ~/.ssh/id_rsa.pub
```

On Linux, you can display the public key in a console with the following command:

```
cat ~/.ssh/id_rsa.pub
```

Copying part is done by selecting the whole public key (starting with "ssh-..." and ending with "...== <your@email.com>", where "<your@email.com>" can be anything - it is essentially a comment to distinguish this particular public key from others). Once selected, use combination of "Ctrl+Shift+C" keys to copy selected text to your clipboard.

## Copy the Public Key to the ThousandEyes VA

Access the web interface of the Virtual Appliance, and navigate to the Appliance Access tab, then copy the public key (which should be on your clipboard) into the "Add New SSH key" text widget.

![](/files/752Ir7jtNJ3vyr8t374w)

The text will show as green if it validates successfully, or red if there is a problem. For most circumstances where there is a problem, remove trailing line feeds.

## Create an SSH Connection to the ThousandEyes VA

Once you have a valid public key on the ThousandEyes VA, you can connect. Connections are established to the VA using the thousandeyes user account, with the passphrase specified while creating the SSH key:

```
$ ssh thousandeyes@<hostname or IP of virtual appliance>
```

The first time you connect to the target virtual appliance, your system will note that the identity has been added.

```
Identity added: /Users/xxxx/.ssh/id_rsa (/Users/xxxx/.ssh/id_rsa)
```

It is strongly recommended that you use static IP addresses for agents in this circumstance, in order to prevent host key checking problems. When you connect, you'll see a warning similar to the one below:

```
The authenticity of host '10.0.100.103 (10.0.100.103)' can't be established.
RSA key fingerprint is bc:15:ab:be:d5:09:xx:xx:xx:xx:a7:5a:6e:d7:df:3a.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '10.0.100.103' (RSA) to the list of known hosts.
```

Once you accept, you're locked into using that IP address unless you modify your list of known hosts. After adding the host, you'll be directed to the home directory of the ThousandEyes VA user.

```
thousandeyes@<hostname or IP of virtual appliance>:~$
```

Now you're connected via SSH.

## Troubleshooting Capabilities

In addition to the files and commands available to regular users on a Linux system, the `thousandeyes` user has access to additional files and commands when you are connected to the appliance that would normally require elevated permissions. The purpose of these files and commands is to facilitate more efficent troubleshooting.

The files and commands listed below are accessible to the `thousandeyes` user without a sudo password:

* `sudoedit /etc/hosts`
* `tcpdump`

The following commands require sudo, but do not need a password:

* `halt`
* `journalctl` (with no arguments)
* `lsof`
* `reboot`
* `shutdown`

You can run `systemctl start`, `stop`, `restart` and `status` for the following services:

* te-agent
* te-browserbot
* te-va

The following package management commands are available:

* `apt-cache`
* `apt-get update`
* `apt-get install` can be used for the following packages:
  * ntpdate
  * te-agent
  * te-agent-utils
  * te-appliance-sidecar
  * te-browserbot
  * te-pa
  * te-va
  * te-va-unlock

You can use the `cat` command to view the following logs:

* /var/log/apt/\*.log
* /var/log/dist-upgrade/\*.log
* /var/log/dmesg
* /var/log/dmesg.\[0-9]\*
* /var/log/kern.log
* /var/log/kern.log.\[0-9]\*

You can use the `zcat` command to view the following compressed logs:

* /var/log/apt/\*.log.\[0-9]\*.gz
* /var/log/dist-upgrade/\*.log.\[0-9]\*.gz
* /var/log/dmesg.\[0-9]\*.gz
* /var/log/kern.log.\[0-9]\*.gz

If troubleshooting requires information from other privileged commands, contact ThousandEyes Support.

For more information about each log file, see the Ubuntu documentation: [Viewing and Monitoring Log Files](https://ubuntu.com/tutorials/viewing-and-monitoring-log-files).


# Connecting to the ThousandEyes Virtual Appliance Using SSH (Windows)

In order to access the command line of a ThousandEyes Virtual Appliance or Physical Appliance, the Appliance can be configured with one or more SSH public keys. An SSH client configured with the corresponding SSH private key can then log into the Appliance's command line.

This article provides instructions for users of a Microsoft Windows operating system to perform the following steps:

1. Obtain an SSH client
2. Create an SSH key pair
3. Configure the ThousandEyes Appliance
4. Create an SSH connection

## Obtain an SSH Client

An SSH application such as PuTTY is required. Download the latest [PuTTY installer](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) (normally the 64-bit MSI) to install the PuTTY suite of programs, most relevantly:

* PuTTY (**putty.exe**): An SSH client
* PuTTYgen (**puttygen.exe**): An SSH key generator
* (Optional) PSCP (**pscp.exe**): A command-line Secure Copy Protocol client, for copying files from the Appliance

Run the MSI installer to installer once the MSI file has been downloaded. Alternatively, individual executables may be downloaded separately from the PuTTY site.

## Create an SSH Key Pair

If you don't already have an SSH key pair (public key and matching private key), you'll need to generate one using PuTTYgen. Open the PuTTYgen program, and follow the steps below.

1. In the **PuTTY Key Generator** window, select the RSA key option and then click the **Generate** button:

![](/files/-M62_WlH8VjtU0Dy0DId)

2. Move your mouse back and forth inside the **Key** field to generate randomness.

![](/files/-MCnEYMqkr-mJKWBZU86)

3. (Optional) Add a passphrase using the fields provided, if desired.
4. Highlight the public key and copy to the clipboard:

![](/files/-M62_WlPJ5TmM0sp8-QV)

5. Save your public and private keys using the **Save public key** and **Save private key** buttons. Note the directory or directories where you save the keys. You'll need the path to the private key for the PuTTY SSH client.

## Configure the ThousandEyes Appliance

The public key of a user's SSH key pair must be present on each agent that is to be accessed. Log into the web interface of a ThousandEyes Appliance, then follow the steps below to configure the Appliance with your public key.

1. On the **Appliance Access** tab, paste the key that was copied in step 4 of the **SSH key creation** section into the **Add New SSH key** field.

NOTE: When pasting the key, make sure the string `ssh-rsa` that prepends the key is present, or the key won't be accepted as valid (see the screenshot below for the correct format of the key).

![](/files/-M62_WlVe9BC22j0xu7G) 2. Click **Add Key**.

The key will be added with the identifying string that follows the key:

![](/files/-M62_WlaCT0u7lmll1r9)

### Add Key Failures

If the key addition fails, most failures are caused by unnecessary beginning and ending lines, comment fields or carriage returns/line feeds. For example, the file saved by the PuTTY Key Generator contains beginning and ending lines and comment fields that need to be removed in order to have a valid public key format:

```
---- BEGIN SSH2 PUBLIC KEY ----
Comment: "An RSA SSH key key example"
AAAAB3NzaC1yc2EAAAABJQAAAQEAgXp4D3V6OGVv24Anh2P4Uh1N1KZ+DP9oT3sx
E8U9MybSho1ev4eZuwso2q3M0tC1YU+PQu1RFd0hzZdcS8zTg7+soopI9HRaOoSL
p5IyywDC28AvoJE8q9DtKZoKKp/cNfyT4h+YiaUx7DMrTYXcLfpEVwu40fqiqmHb
s42RJ/yVMq4MKYEp0AvZcC8l/ByYvU9b/ogEKI8g175RLgVVmJqSaZW/w/ZhzG7u
89q1F1bYgJlEbrINSoBKC7CPyKB8N3KqTl1vOqiqSe6DSCzLIDk+NPEPSWGf3LoO
bAKcV9O2ml74rCipBBGyslsQVIINLxyUpXFC42/sS1ZN+MXYnQ==
---- END SSH2 PUBLIC KEY ----
```

If you copy the public key from the saved file rather than from the PuTTYGen window in step 4 of the **Create an SSH key pair** section, remove the BEGIN and END lines, the Comment: line(s) and any carriage return, new line or line feed characters. The correct format should look like this:

```
ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAQEAgXp4D3V6OGVv24Anh2P4Uh1N1KZ+DP9oT3sxE8U9MybSho1ev4eZuwso2q3M0tC1YU+PQu1RFd0hzZdcS8zTg7+soopI9HRaOoSLp5IyywDC28AvoJE8q9DtKZoKKp/cNfyT4h+YiaUx7DMrTYXcLfpEVwu40fqiqmHbs42RJ/yVMq4MKYEp0AvZcC8l/ByYvU9b/ogEKI8g175RLgVVmJqSaZW/w/ZhzG7u89q1F1bYgJlEbrINSoBKC7CPyKB8N3KqTl1vOqiqSe6DSCzLIDk+NPEPSWGf3LoObAKcV9O2ml74rCipBBGyslsQVIINLxyUpXFC42/sS1ZN+MXYnQ== An RSA SSH key example
```

If attempts are failing despite following these instructions, then copy the above example and attempt to add it. If the example key addition is successful, the failure is likely due to a carriage return, new line or line feed character that remains in the newly generated key.

The example key can be immediately deleted by clicking the button to the right of the key, in the listing of keys added to the Appliance.

## Create an SSH Connection

Once a public key has been installed on the Appliance, follow the instructions below to configure PuTTY and log into the command line of the Appliance.

1. Run the PuTTY program (putty.exe).
2. In the PuTTY Configuration window's **Category** section, open the **Connection > Data** panel.
3. Enter the username "thousandeyes" in the **Auto-login username** field.

![](/files/-M62_WlhpsPuFVba7dXx)

4. In the PuTTY Configuration window's **Category** section, open the **Connection** > **SSH** > **Auth** panel.
5. Click **Browse** and navigate to the location selected in Step 5 of the **Create an SSH key pair** section above.

![](/files/-M62_WloFcEgQiBuZacM)

6. In the PuTTY Configuration window's **Category** section, open the **Session** panel.
7. Enter the IP address or hostname of the Enterprise Agent in the **Host Name (or IP address)** field.
8. Enter a name for this PuTTY session in the **Saved Sessions** field.
9. Click **Save** to save the session for future uses.

![](/files/-M62_Wlur0n3CCSzDhqK)

10. Click **Open** to open the SSH connection to the Appliance's command line.
11. If a passphrase was created in Step 3 of the **Create an SSH key pair** section, provide the passphrase to the SSH key.

![](/files/-M62_Wm0fTMZ-uMwiKjS)

12. If the login is successful, the prompt "thousandeyes\@appliance\_hostname:\~ appears, indicating the user is in the home directory of the "thousandeyes" user.

Now you're connected via SSH.

## Troubleshooting

**Connection problem symptoms when using PuTTY SSH client:**

* `Error: Server unexpectedly closed network connection` error message
* `fatal: no matching mac found:...` error message

**Solution:** Make sure that PuTTY is at the current version as these errors have been encountered when using older versions of PuTTY.


# Static IP Addresses for ThousandEyes Repositories

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

ThousandEyes Enterprise Agents update their ThousandEyes software from repositories: **apk.thousandeyes.com** for Docker containers, **apt.thousandeyes.com** for Appliances and Ubuntu-based Linux package installations, and **yum.thousandeyes.com** for Red Hat, CentOS and Oracle Linux-based Linux package installations.

The servers that host apk.thousandeyes.com, apt.thousandeyes.com, and yum.thousandeyes.com are based in a content delivery network (CDN) for fast download performance and for redundancy. Using this CDN results in a dynamic mapping of the domain names to IP addresses. The IP addresses can change at any time, and the change frequency or timing is not controlled by ThousandEyes.

## Static IPv4 and IPv6 Addresses

For customers whose Enterprise Agents' outbound network connections must be restricted to destinations with static IP addresses (or domain names that resolve to static IP addresses) ThousandEyes provides two additional repositories, **apkproxy.thousandeyes.com**, **aptproxy.thousandeyes.com** and **yumproxy.thousandeyes.com**. All domain names map to two static IPv4 and two static IPv6 addresses hosted in Amazon Web Services.

| IP Address               | AWS Region                      |
| ------------------------ | ------------------------------- |
| 54.176.31.213            | us-west-1 (Northern California) |
| 204.236.186.250          | us-west-1 (Northern California) |
| 2600:1f1c:89b:bf01::ffff | us-west-1 (Northern California) |
| 2600:1f1c:89b:bf02::ffff | us-west-1 (Northern California) |

Customers may use these proxy domain names in the repository configuration files of the Enterprise Agent systems, and use the domain names or IP addresses in the configuration of network devices if security policies or technical limitations (firewalls or routers which which cannot resolve domain names in rules or ACLs) require static IP address configuration.

For guidance on changing the repository location used by your Enterprise Agents, refer to the relevant steps for your installation type in how to [modify repository files on your Agents](https://docs.thousandeyes.com/product-documentation/enterprise-agents/configuring-a-local-mirror-of-the-thousandeyes-package-repository).

{% hint style="warning" %}
We strongly recommend using the default configuration if at all possible. ThousandEyes attempts to maintain the stability of these IP addresses, but the addresses may change without warning.
{% endhint %}

## Troubleshooting

For customers using proxy repository addresses, if the above IP addresses change, then Enterprise Agent software packages will not update. If you are receiving warnings about out-of-date Enterprise Agent software on the **Network & App Synthetics > Agent Settings > Enterprise Agents** page, run the relevant command for your installation to determine whether the IP addresses have changed:

* `dig apkproxy.thousandeyes.com`

  `dig aptproxy.thousandeyes.com`

  `dig yumproxy.thousandeyes.com`
* `nslookup apkproxy.thousandeyes.com`

  `nslookup aptproxy.thousandeyes.com`

  `nslookup yumproxy.thousandeyes.com`

The above commands should return two IP addresses. One or both may change.


# Firewall Configuration for Enterprise Agents

When installing a ThousandEyes Enterprise Agent behind a firewall or similar device (such as a router with access control lists (ACLs)), the device must be configured with rules that allow the Enterprise Agent to register with the ThousandEyes platform, execute tests, report test results, and access necessary infrastructure services such as the domain name service (DNS), the Network Time Protocol (NTP) and repositories for software package updates.

This article provides a complete set of information to allow Enterprise Agent network communication to traverse a firewall or similar device. For administrators wishing to quickly install an Enterprise Agent, review the [Base Rules](#base-rules) section for the instructions required to register the agent in the ThousandEyes platform. Software updates are covered in the [Installation Type Rules](#installation-type-rules) section.

## Introduction

A firewall rule or ACL for Enterprise Agent communication is specified using one or more of the following criteria:

* Destination IP address(es) or DNS domain name(s)
* Destination port numbers (if the protocol is TCP or UDP)
* Protocol (TCP, UDP, or ICMP)
* Direction (outbound from the agent unless otherwise noted)

{% hint style="info" %}
To use domain names in rules or ACLs, the firewall or other filtering device must support resolution of domain names to IP addresses.
{% endhint %}

{% hint style="info" %}
In the tables below, any destination specified only by domain name must be resolved by the customer if an IP address is required. Many common tools such as **dig**, **drill** or **nslookup** can be used for resolving DNS names to IP addresses. Note that third-party (non-ThousandEyes) DNS mappings may change without warning.
{% endhint %}

{% hint style="warning" %}
**thousandeyes.com** domain names are not currently protected by DNSSEC.
{% endhint %}

{% hint style="warning" %}
Direction assumes rules or ACLs use dynamic/stateful filtering, which permit response packets automatically. If your firewall or filter device uses static packet filters, you must create rules in both directions of the communication.
{% endhint %}

### Network Address Translation

Firewalls or similar devices which use rules or ACLs are typically also capable of performing network address translation (NAT). If your Enterprise Agent is behind a NAT device, then ensure that the necessary NAT rule for your agent exists for the types of tests that the agent will run. ThousandEyes recommends creating static, "one-to-one" NAT rules for the agent as the simplest configuration for proper test function.

### Proxy Servers

Some organizations require an Enterprise Agent to use a proxy server for HTTP-based communication. A proxy may be configured with an allowed list of destinations, which are normally specified by domain names (some proxies may require IP addresses or both). For environments which require a proxy, consult your organization's proxy administrator and the articles [Installing Enterprise Agents in Proxy Environments](https://docs.thousandeyes.com/product-documentation/enterprise-agents/installing-enterprise-agents-in-proxy-environments) and [Configuring an Enterprise Agent to Use a Proxy Server](https://docs.thousandeyes.com/product-documentation/enterprise-agents/configuring-an-enterprise-agent-to-use-a-proxy-server).

Agents will still require configuration of rules or ACLs for non-HTTP based communication, which is typically not sent via proxy servers. Most notably, the Network layer data (overview metrics and path visualization) can only be obtained to the proxy but cannot be transmitted through a proxy to the target server. If Network layer data to the target server is desired, then the proxy will need to be bypassed and firewall rules or ACLs configured to allow the Network layer communication directly from the agent to the target.

## Rules Overview

Rules are divided into four section: 1) base rules that are required for all agents, 2) rules specific to an agent's installation type, 3) rules required for tests run by an agent, and miscellaneous rules. The latter three categories have multiple sections and subsections. To construct rules for your installation, review the relevant sections and subsections in each category to identify all needed rules.

Use the links in the list below for quick navigation to a specific section of this document.

1. [Base rules required for all agents](#base-rules)
2. [Rules specific to an agent's installation type](#installation-type-rules)
   * [Appliances](#appliances)
     * [Raspberry Pi](#raspberry-pi)
   * [Docker Containers (including Cisco Application Hosting and Meraki Agents)](#docker-and-caf-containers)
   * [Linux packages](#linux-packages)
     * [Ubuntu](#ubuntu)
     * [Red Hat Enterprise Linux, CentOS and Oracle Linux](#red-hat)
3. [Rules required for tests run by an agent](#test-rules)
   * [Routing Layer](#routing-layer)
     * [BGP](#bgp)
   * [Network Layer](#network-layer)
     * [Agent-to-server](#agent-to-server)
     * [Agent-to-agent](#agent-to-agent)
   * [DNS Layer](#dns-layer)
     * [DNS Server](#dns-server)
     * [DNS Trace](#dns-trace)
     * [DNSSEC](#dnssec)
   * [Web Layer](#web-layer)
     * [HTTP Server](#http-server)
     * [Page Load and Transaction](#page-load-and-transaction)
     * [FTP Server](#ftp-server)
   * [Voice Layer](#voice-layer)
     * [SIP Server](#sip-server)
     * [RTP Stream](#rtp-stream)
4. [Miscellaneous](#miscellaneous)
   * [Kerberos and Active Directory](#kerberos-and-active-directory)
   * [Proxies](#proxies)
     * [Proxy Servers](#proxy-servers)
     * [PAC file Servers](#pac-file-servers)
   * [Device Layer](#voice-layer)
   * [Internet Insights](#internet-insights)

{% hint style="info" %}
Rules in each category are cumulative. Add base rules plus the applicable rules for your Enterprise Agent installation type and tests and to obtain the complete ruleset needed for a given agent.
{% endhint %}

## Base Rules

The sections below provide the base firewall communication rules required for the installation and full functionality of ThousandEyes Enterprise Agents. The rules are region specific.

{% hint style="info" %}
The firewall configuration rules for the ThousandEyes for Government instance are available here: [ThousandEyes for Government Firewall Configuration](https://docs.thousandeyes.com/thousandeyes-for-government/thousandeyes-for-government#thousandeyes-for-government-firewall-configuration).
{% endhint %}

{% hint style="info" %}
Some organizations may not require rules for DNS and/or NTP servers if both the agent and servers are located inside the organization's network, and thus this communication is not blocked by existing rules or ACLs.

Additionally, ThousandEyes recommends permitting all ICMP error message types inbound to the agent in order to ensure full network functionality. If your firewall is fully stateful/dynamic for all ICMP error response types, then no rules are required. For firewalls which do not dynamically allow ICMP error messages in response to packets sent outbound that encounter the error conditions, we recommend allowing inbound the following:

Consult your firewall vendor's documentation or contact their technical support to determine whether you need to add rules to allow these ICMP error message responses. Be aware that explicit NAT rules may also be required for the inbound ICMP if the agent is behind a NAT IP address.
{% endhint %}

| **Protocol** | **ICMP Types** |
| ------------ | -------------- |
| IPv4         | 3, 11          |
| IPv6         | 1-4, 129       |

### United States (US1) Region Infrastructure

| **Protocol** | **Port**   | **Destination address and/or name**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | **Notes**                         |
| ------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| TCP, UDP     | 53         | DNS server IP address(es)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Domain Name Service               |
| TCP, UDP     | 9119, 9120 | ntrav.thousandeyes.com or 54.241.50.7, 54.176.41.14                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | NAT Traversal                     |
| UDP          | 123        | NTP server domain names or IP addresses                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Time synchronization              |
| TCP          | 443        | c1.thousandeyes.com, c1.agt.thousandeyes.com, sc1.thousandeyes.com, crashreports.thousandeyes.com, data1.agt.thousandeyes.com, api.thousandeyes.com, registry.agt.thousandeyes.com or 13.52.142.100, 13.248.134.58, 13.248.148.46, 13.248.149.2, 13.248.155.8 , 13.248.200.34, 13.248.202.9 , 13.248.202.19, 13.248.203.51, 13.248.204.16, 13.248.209.13, 13.248.210.21, 13.248.217.17, 18.144.148.196, 18.144.149.12, 50.18.29.173, 50.18.71.33, 50.18.101.91, 50.18.147.222, 50.18.191.119, 52.8.4.84, 52.8.104.182, 52.8.189.216, 52.9.5.97, 52.9.192.109, 54.151.40.182, 54.151.125.71, 54.153.4.162, 54.153.76.24, 54.176.41.14, 54.176.57.120, 54.176.79.58, 54.176.123.201, 54.176.128.223, 54.176.144.255, 54.176.253.85, 54.177.34.231, 54.177.66.87, 54.177.159.228, 54.177.244.79, 54.193.142.147, 54.215.2.49, 54.215.23.174, 54.215.97.223, 54.219.6.129, 54.219.8.137, 54.219.22.100, 54.219.78.196, 54.219.101.241, 54.219.105.52, 54.219.249.111, 54.241.50.7, 54.241.92.230, 54.241.205.203, 54.241.250.221, 75.2.27.3, 75.2.38.56, 75.2.45.13, 75.2.49.1, 75.2.66.34, 75.2.81.6, 75.2.95.38, 75.2.105.19, 75.2.122.52, 76.223.1.146, 76.223.11.132, 76.223.22.131, 76.223.22.172, 76.223.68.153, 76.223.69.131, 76.223.72.156, 76.223.76.176, 76.223.82.139, 76.223.86.189, 76.223.88.183, 76.223.92.188, 99.83.133.153, 99.83.133.174, 99.83.136.191, 99.83.139.130, 99.83.143.133, 99.83.165.166, 99.83.227.178, 99.83.242.129, 99.83.250.143, 184.169.143.99, 192.150.160.17, 204.236.184.131, 204.236.190.123, 2600:9000:a402:3156:ec1c:12bb:2fe3:5cfe, 2600:9000:a71c:9fff:69db:1ae2:5e68:87fa, 2600:9000:a402:3156:16f1:9d65:eafc:2b7f, 2600:9000:a71c:9fff:6e1b:8d49:2cd0:fe34, 2600:9000:a71c:9fff:9fd2:e70e:cae7:1ab7, 2600:9000:a402:3156:1a3c:ceb1:d30c:dabe, 2600:9000:a402:3156:fdf3:d270:bb9c:9606, 2600:9000:a71c:9fff:ea13:4e6a:4c50:53a6 | ThousandEyes Agent infrastructure |

### United States (US2) Region Infrastructure

| **Protocol** | **Port**   | **Destination address and/or name**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | **Notes**                         |
| ------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| TCP, UDP     | 53         | DNS server IP address(es)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Domain Name Service               |
| TCP, UDP     | 9119, 9120 | ntrav.agt.us2.thousandeyes.com or 3.132.6.211, 18.116.57.17                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | NAT Traversal                     |
| UDP          | 123        | NTP server domain names or IP addresses                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Time synchronization              |
| TCP          | 443        | c1.us2.thousandeyes.com, c1.agt.us2.thousandeyes.com, sc1.thousandeyes.com, sc1.us2.thousandeyes.com, crashreports.us2.thousandeyes.com, crashreports.agt.us2.thousandeyes.com, data1.agt.us2.thousandeyes.com, sc1.agt.us2.thousandeyes.com, ntrav.agt.us2.thousandeyes.com or 3.13.54.169, 3.17.98.26, 3.18.18.42, 3.33.203.108, 3.132.6.211, 3.134.227.22, 3.138.52.162, 3.141.159.49, 13.248.163.136, 13.248.183.146, 15.197.252.168, 18.116.57.17, 35.81.172.197, 35.155.240.202, 44.227.213.61, 52.27.149.70, 52.32.30.54, 52.89.210.182, 75.2.99.138, 76.223.43.74, 76.223.44.124, 99.83.249.82, 75.2.105.19, 99.83.165.166, 2600:9000:a51a:57fb:67d1:c825:2558:d3d8, 2600:9000:a617:a514:9d10:8ff1:33e1:60a0, 2600:9000:a617:a514:8e0f:8fa0:22d:daf6, 2600:9000:a51a:57fb:441d:f096:8886:7172, 2600:9000:a617:a514:238c:87f8:4ac6:f883, 2600:9000:a51a:57fb:784e:f506:b2e1:672e, 2600:9000:a51a:57fb:e568:20dd:1cfe:d2f2, 2600:9000:a71c:9fff:69db:1ae2:5e68:87fa, 2600:9000:a617:a514:c7ea:433a:c8aa:b257, 2600:9000:a402:3156:ec1c:12bb:2fe3:5cfe | ThousandEyes Agent infrastructure |

### Europe (EU) Region Infrastructure

| **Protocol** | **Port**   | **Destination address and/or name**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | **Notes**                         |
| ------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| TCP, UDP     | 53         | DNS server IP address(es)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Domain Name Service               |
| TCP, UDP     | 9119, 9120 | ntrav.agt.eu1.thousandeyes.com or 18.196.154.132, 18.198.93.108                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | NAT Traversal                     |
| UDP          | 123        | NTP server domain names or IP addresses                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Time synchronization              |
| TCP          | 443        | c1.eu1.thousandeyes.com, c1.agt.eu1.thousandeyes.com, sc1.eu1.thousandeyes.com, crashreports.eu1.thousandeyes.com, crashreports.agt.eu1.thousandeyes.com, data1.agt.eu1.thousandeyes.com, api.thousandeyes.com, registry.agt.thousandeyes.com, sc1.thousandeyes.com, sc1.agt.eu1.thousandeyes.com or 3.33.164.16, 3.33.187.44, 3.33.215.45, 3.64.86.17, 3.64.141.190, 3.65.47.201, 3.65.166.122, 3.65.171.231, 3.65.171.239, 3.65.185.162, 3.65.191.148, 3.66.9.208, 3.66.71.28, 3.66.128.248, 3.67.61.181, 3.67.218.64, 3.69.141.127, 3.70.151.143, 3.122.35.251, 3.123.81.97, 3.123.89.250, 3.123.107.208, 3.123.252.103, 3.124.9.190, 3.124.252.11, 3.125.85.224, 3.125.254.106, 3.126.0.158, 3.126.74.162, 3.127.83.94, 3.127.120.153, 3.127.178.204, 13.248.161.94, 13.248.168.65, 13.248.183.127, 13.248.200.34, 13.248.235.103, 15.197.167.77, 15.197.185.73, 15.197.255.121, 18.156.19.75, 18.156.88.25, 18.157.218.95, 18.158.27.194, 18.158.53.4, 18.158.92.124, 18.159.84.31, 18.159.94.223, 18.159.99.39, 18.184.56.44, 18.185.182.46, 18.185.208.167, 18.192.82.10, 18.192.201.226, 18.193.23.116, 18.193.229.212, 18.194.73.211, 18.195.106.116, 18.195.137.74, 18.195.247.42, 18.196.71.170, 18.196.154.132, 18.197.136.39, 18.198.93.108, 18.198.102.67, 18.198.145.229, 35.71.129.45, 35.71.130.48, 35.71.139.15, 35.71.156.36, 35.71.163.48, 35.71.179.10, 35.157.204.27, 52.28.224.133, 52.57.69.190, 52.57.199.196, 52.58.234.168, 52.223.3.68, 52.223.12.120, 52.223.23.95, 52.223.32.91, 52.223.46.66, 52.223.50.116, 75.2.42.105, 75.2.72.82, 75.2.105.19, 76.223.33.5, 76.223.46.53, 76.223.63.14, 76.223.86.189, 76.223.116.8, 99.83.165.166, 99.83.171.52, 99.83.208.32, 2600:9000:a71f:f2a:3882:322c:4f31:8fb5, 2600:9000:a419:70ce:42b:8b42:5402:ca40, 2600:9000:a71f:f2a:2cce:e68b:6f1d:c5c6, 2600:9000:a419:70ce:eef3:7c97:e2b7:348c, 2600:9000:a71f:f2a:57ff:f7bc:e892:a871, 2600:9000:a419:70ce:9ca0:c090:375:2210, 2600:9000:a419:70ce:f120:ba93:e202:47fc, 2600:9000:a71f:f2a:9e2a:cb4b:58d2:b9e1 | ThousandEyes Agent infrastructure |

## Installation Type Rules

Installation types are displayed in the [Add New Enterprise Agent](https://app.thousandeyes.com/network-app-synthetics/agent-settings/enterprise/?section=agents\&add-agent) dialog of the [Enterprise Agents](https://app.thousandeyes.com/network-app-synthetics/agent-settings/enterprise/?section=agents) page. Additionally, the "Type" filter of the Enterprise Agents page displays a listing of the types of currently installed (active and deactivated) Enterprise Agents belonging to the current account group.

Determine the installation type of your Enterprise Agents and refer the applicable section(s) below. Some installation types fall under more than one section's set of rules (i.e. rules are cumulative, per the infobox above). For example, a Raspberry Pi appliance requires the rules in the **Appliances** section, as well as the **Raspberry Pi** subsection.

### Appliances

ThousandEyes appliances are based on the Ubuntu Linux operating system, and require access to both the generic Ubuntu software package repositories and the ThousandEyes repository to update software automatically. The following rules are required for agents distributed in virtual machine format (virtual appliances and Hyper-V appliances) and for Physical Appliances and Raspberry Pi-based agents which are distributed via ISO image:

| **Protocol** | **Port**  | **Destination**       | **Notes**                           |
| ------------ | --------- | --------------------- | ----------------------------------- |
| TCP          | 80        | archive.ubuntu.com    | Ubuntu Linux package repository     |
| TCP          | 80        | security.ubuntu.com   | Ubuntu Linux package repository     |
| TCP          | 80        | archive.canonical.com | Ubuntu Linux package repository     |
| TCP          | 443       | changelogs.ubuntu.com | Ubuntu Linux package repository     |
| TCP          | 80 or 443 | apt.thousandeyes.com  | ThousandEyes APT package repository |
| TCP          | 443       | download.docker.com   | Docker package repository           |

Select port 80 or port 443 depending on your organization's security requirements.

The apt.thousandeyes.com repository is located in a content delivery network (CDN), where IP addresses can change without notice. For customers requiring a static IP address for the ThousandEyes APT repository, the aptproxy.thousandeyes.com domain name will always resolve to the same IP addresses. See the ThousandEyes article [Static IP Addresses for ThousandEyes Repositories](https://docs.thousandeyes.com/product-documentation/enterprise-agents/static-ip-addresses-for-thousandeyes-repositories) for additional information.

ThousandEyes appliances, which include virtual appliances, physical appliances, Hyper-V appliances, and agents installed on Raspberry Pi platforms -- also provide a web-based administration interface, as well as an SSH server for command-line management. The direction of the connections are inbound to the agent (agent IP address is the destination). If web or SSH connections traverse a firewall, the following rules are required:

| **Protocol** | **Port** | **Destination**  | **Notes**            |
| ------------ | -------- | ---------------- | -------------------- |
| TCP          | 443      | Agent IP address | Inbound to the agent |
| TCP          | 22       | Agent IP address | Inbound to the agent |

For more information, see [ThousandEyes Virtual Appliance Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-virtual-appliance-installation).

#### Raspberry Pi

The following rule is required for agents installed on Raspberry Pi 4 hardware:

| **Protocol** | **Port** | **Destination**  | **Notes**                       |
| ------------ | -------- | ---------------- | ------------------------------- |
| TCP          | 80       | ports.ubuntu.com | Ubuntu Linux package repository |

### Docker and CAF Containers

ThousandEyes agent software for Docker-based containers, including Cisco devices using the Cisco application hosting framework (CAF), is supplied by the ThousandEyes APK repository apk.thousandeyes.com repository. Agent software has dependencies on software packages provided in common repositories that typically are required for the operating system. Consult your operating system's documentation for the locations of these repositories and construct rules as required.

The apk.thousandeyes.com repository is located in a content delivery network (CDN), where IP addresses can change without notice. For customers requiring a static IP address for the ThousandEyes repositories, the apkproxy.thousandeyes.com domain name will always resolve to the same IP addresses. See the ThousandEyes article [Static IP Addresses for ThousandEyes Repositories](https://docs.thousandeyes.com/product-documentation/enterprise-agents/static-ip-addresses-for-thousandeyes-repositories) for additional information.

The following rules are required only for installation of Docker container-based agents that download images maintained in the Docker registry (as installed with the default docker pull command; see [Enterprise Agent Deployment Using Docker](https://docs.thousandeyes.com/product-documentation/enterprise-agents/enterprise-agent-deployment-using-docker#installing-the-enterprise-agent-image)). This includes deployments of Docker for Linux, Webex VMN, and Meraki.

| **Protocol** | **Port** | **Destination**                  | **Notes**                          |
| ------------ | -------- | -------------------------------- | ---------------------------------- |
| TCP          | 443      | hub.docker.com                   | Docker-based agents (install only) |
| TCP          | 443      | auth.docker.io                   | Docker-based agents (install only) |
| TCP          | 443      | registry.docker.io               | Docker-based agents (install only) |
| TCP          | 443      | production.cloudflare.docker.com | Docker-based agents (install only) |

The following rules are required for Docker installations to keep the software updated inside the container:

| **Protocol** | **Port**  | **Destination**        | **Notes**                           |
| ------------ | --------- | ---------------------- | ----------------------------------- |
| TCP          | 80 or 443 | apk.thousandeyes.com   | ThousandEyes APK package repository |
| TCP          | 80 or 443 | dl-cdn.alpinelinux.org | Alpine Linux package repository     |

Select port 80 or port 443 depending on your organization's security requirements.

### Linux Packages

ThousandEyes agent software for linux packages is supplied by the ThousandEyes APT repository apt.thousandeyes.com (for Ubuntu), or the ThousandEyes YUM repository yum.thousandeyes.com (For Red Hat, CentOS and Oracle Linux). Agent software has dependencies on software packages provided in common repositories that typically are required for the operating system. Consult your operating system's documentation for the locations of these repositories and construct rules as required.

The `apt.thousandeyes.com` and `yum.thousandeyes.com` repositories are located in a content delivery network (CDN), where IP addresses can change without notice. For customers requiring a static IP address for the ThousandEyes repositories, the `aptproxy.thousandeyes.com` and `yumproxy.thousandeyes.com` domain names will always resolve to the same IP addresses. See the ThousandEyes article [Static IP Addresses for ThousandEyes Repositories](https://docs.thousandeyes.com/product-documentation/enterprise-agents/static-ip-addresses-for-thousandeyes-repositories) for additional information.

For all Linux package installs, if the ThousandEyes BrowserBot package has been installed (implements the Page Load and the Web Transaction test types) and if host-based Linux-based firewall software is employed then following rule is required:

| **Protocol** | **Port** | **Destination** | **Notes**                                          |
| ------------ | -------- | --------------- | -------------------------------------------------- |
| TCP          | 8998     | 127.0.0.1       | BrowserBot sandbox (for host-based firewalls only) |

Agent processes make internal network connections (i.e. not using the physical network) to the BrowserBot sandbox, which listens on port 8998/TCP of the loopback interface (normally uses IP address 127.0.0.1). Configure the host-based firewall to allow connections to the loopback IP address on the specified port.

#### Ubuntu

The following rules are required for Ubuntu Linux package installations:

| **Protocol** | **Port**  | **Destination**      | **Notes**                           |
| ------------ | --------- | -------------------- | ----------------------------------- |
| TCP          | 80 or 443 | apt.thousandeyes.com | ThousandEyes APT package repository |

Select port 80 or port 443 depending on your organization's security requirements.

#### Red Hat

The following rules are required for Red Hat Enterprise Linux, CentOS and Oracle Linux package installations:

| **Protocol** | **Port**  | **Destination**      | **Notes**                           |
| ------------ | --------- | -------------------- | ----------------------------------- |
| TCP          | 80 or 443 | yum.thousandeyes.com | ThousandEyes YUM package repository |
| TCP          | 443       | dl.fedoraproject.org | Red Hat Fedora package repository   |

Select port 80 or port 443 depending on your organization's security requirements.

## Test Rules

The protocol, port, and destination of rules to permit test traffic will depend on the type of test created and the target (destination) of the test. Normally, the direction for test rules is outbound from the agent. However, for agent-to-agent tests and RTP stream tests, agents are both sources and target of the test, so the direction for test rules is both outbound and inbound, as indicated below.

The sections below use the default ports for the test types. For example, a web layer test will need outbound access on TCP port 80 and/or 443 by default. If a test is configured with a non-default port number then the rule must use that port number instead of the default.

Additionally, most non-network layer tests include network measurements via the **Perform network measurements** setting (configured by default, under the **Advanced Settings** tab of the test configuration). When using **Perform network measurements**, additional rules may be required for those measurements, in addition to any rules based on the test type. Use the instructions in the [Agent-to-Server](#agent-to-server) section below to add any needed rule for your test's network measurements, treating the **Protocol** field on your test's Advanced Settings tab as the **Protocol** field in the agent-to-server test.

Similarly, if the **Perform network measurements** setting includes **Collect BGP data** then use the instructions in the [Routing Layer](#routing-layer) section below to add any needed rules for your test's network measurements.

### Routing Layer

The Routing Layer contains the BGP test type which provides the BGP Route Visualization. The BGP Route Visualization is also part of the **Perform network measurements** setting of other test types. BGP data is supplied by public BGP Monitors which report data to ThousandEyes, or customers may create [Private BGP Monitors](https://app.thousandeyes.com/settings/bgp-sessions/) using their own BGP-enabled devices to peer with ThousandEyes. If a Private BGP Monitor is used for a BGP test or as part of other tests' Network metrics, and that Private BGP Monitor traverses a firewall, then a firewall rule or ACL may be required.

Private BGP Monitors are independent of Enterprise Agents, but can provide data for tests run by Enterprise Agents, so are included in this article. If your organization uses Private BGP Monitors, review the article [Inside-Out BGP Visibility](https://docs.thousandeyes.com/product-documentation/thousandeyes-basics/inside-out-bgp-visibility) for additional information.

#### BGP

Private BGP Monitors peer with a router in the ThousandEyes infrastructure. When the private BGP monitor is first configured, customers are sent the domain name of the ThousandEyes peer, along with peering instructions. If a private BGP monitor traverses a firewall, then the following firewall rule or ACL may be required.

| **Protocol** | **Port** | **Destination**   | **Notes**                                                       |
| ------------ | -------- | ----------------- | --------------------------------------------------------------- |
| TCP          | 179      | ThousandEyes peer | Obtain peer's domain name from configuration instructions email |

The source is the customer's BGP-speaking device, not an Enterprise Agent. The destination information can be obtained from the email that ThousandEyes sends after a private BGP monitor is requested. ThousandEyes emails configuration information to the requestor, including the peer's domain name (for example bgpc1.thousandeyes.com) or IP address.

### Network Layer

Network layer tests permit a choice of protocol (TCP, UDP, and/or ICMP depending on the test type). Create rules with the protocol configured in the test's **Protocol** setting.

#### Agent-to-Server

Agent-to-server tests default to TCP as the protocol and 80 as the port. If a different port number is used in the test, use that port number in the rule.

| **Protocol** | **Port** | **Destination** | **Notes**                             |
| ------------ | -------- | --------------- | ------------------------------------- |
| TCP          | 80       | test target     | If test's **Protocol** setting is TCP |

Alternatively, if ICMP is selected in the **Protocol** field on the Basic Configuration tab of the test settings then use the following rule.

| **Protocol** | **ICMP service** | **Destination** | **Notes**                                                          |
| ------------ | ---------------- | --------------- | ------------------------------------------------------------------ |
| ICMP         | ping             | test target     | Overview metrics (Loss, Latency and Jitter) and Path Visualization |

ICMP uses [Types and Codes](https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml), rather than port numbers. For the "Overview" metrics rule, the outbound ICMP code and type uses Type 8, Code 0 (Echo Request) and the return/inbound ICMP uses code 0, type 0 (Echo Reply). Many firewalls refer to this combination as the "ping" service or object.

For the Path Visualization, the outbound ICMP packets use type 8, code 0 (Echo Request) and the returning inbound ICMP packets use both type 0, code 0 (Echo Reply) and type 11, code 0 (Time to Live exceeded in Transit). Many firewalls refer to this combination as the "traceroute" service or object. Normally, a separate rule for traceroute is not needed because stateful firewalls associate the outbound packets (whether TCP, UDP or ICMP) with the inbound ICMP type 11 packets generated by the outbound packets. However, if a firewall cannot make this association, a second rule to allow the type 11 packets inbound to the agent may be required. Such a rule may be similar to the above ICMP rule but with the "traceroute" object, or may require a rule for ICMP type 11 to the agent as destination, from any source.

Note also that "many-to-one" network address translation may not make the association between outbound packets and incoming ICMP type 11 packets, and will block the type 11 packets. A one-to-one NAT rule will need to be configured to allow the inbound ICMP type 11 packets to be correctly translated.

#### Agent-to-Agent

Agent-to-agent tests default to TCP as the protocol and 49153 as the port. Alternatively, if UDP is selected in the **Protocol** field on the Basic Configuration tab of the test settings then use UDP. If a different port number is used in the test, use that port number in the rule.

| **Protocol** | **Port** | **Destination** | **Notes**                                      |
| ------------ | -------- | --------------- | ---------------------------------------------- |
| TCP or UDP   | 49153    | test target     | Use TCP or UDP per test's **Protocol** setting |

With agent-to-agent tests, if one or both agents is behind a network address translation device, the NAT traversal feature may be required, particularly if the NAT is not a one-to-one NAT. If required, the **Behind a NAT** box must be checked on the Enterprise Agent's Settings page.

NAT traversal requires communication to the ThousandEyes NAT traversal service, which may require an additional rule. Use the first rule for TCP-based tests; the second for UDP-based tests.

| **Protocol** | **Port**      | **Destination**        | **Notes**                      |
| ------------ | ------------- | ---------------------- | ------------------------------ |
| TCP          | 9119 and 9120 | ntrav.thousandeyes.com | TCP-based agent-to-agent tests |
| TCP and UDP  | 9119 and 9120 | ntrav.thousandeyes.com | UDP-based agent-to-agent tests |

If a many-to-one type of NAT is used, then the NAT device should meet the criteria in the article [NAT Traversal for Agent-to-Agent Tests](https://docs.thousandeyes.com/product-documentation/enterprise-agents/nat-traversal-for-agent-to-agent-tests) for agent-to-agent tests.

### DNS Layer

DNS Layer tests all use a destination port of 53. The port is not user-configurable. Additionally, DNS Layer tests use only one transport protocol, either UDP or TCP. Truncated responses will never result in a test switching from UDP to TCP.

#### DNS Server

DNS Server tests default to UDP as the protocol, as specified in the **Transport** field on the Advanced Settings tab of the test settings. Alternatively, TCP may be used.

| **Protocol** | **Port** | **Destination** | **Notes**                                       |
| ------------ | -------- | --------------- | ----------------------------------------------- |
| UDP or TCP   | 53       | test target     | Use UDP or TCP per test's **Transport** setting |

#### DNS Trace

DNS Trace tests default to UDP as the protocol, as specified in the **Transport** field on the Advanced Settings tab of the test settings. Alternatively, TCP may be used.

| **Protocol** | **Port** | **Destination**  | **Notes**                                       |
| ------------ | -------- | ---------------- | ----------------------------------------------- |
| UDP or TCP   | 53       | all destinations | Use UDP or TCP per test's **Transport** setting |

Normally, the test must have access to all destinations in order to access all of the servers required to perform iterative queries to authoritative nameservers in the DNS hierarchy, starting from the root nameservers.

#### DNSSEC

DNSSEC tests are similar to DNS Trace tests, except that DNSSEC tests always use UDP as the transport protocol.

| **Protocol** | **Port** | **Destination**  | **Notes** |
| ------------ | -------- | ---------------- | --------- |
| UDP          | 53       | all destinations |           |

Normally, the test must have access to all destinations in order to access all of the servers required to perform iterative queries to authoritative nameservers in the DNS hierarchy, starting from the root nameservers.

### Web Layer

Web layer tests (other than FTP Server tests) differ from other tests in that the target of the test is potentially (or likely) not the only destination for traffic from the agent. HTTP Server tests can receive HTTP redirects to domains other than the target domain name or IP address. Moreover. Page Load and Transaction tests load entire web pages which typically require connections to many destinations. For this reason, the **Destination** column in the Page Load and Transaction test section indicates "all destinations". If the domains to which requests are made are known, rules can be created which specify only those domains.

#### HTTP Server

The HTTP Server test uses port 80 by default if the test target is configured with the `http://` scheme and uses port 443 if configured with the `https://` scheme. If a non-default port number is used by the target server, use that port number in the rule.

| **Protocol** | **Port**  | **Destination** | **Notes**                                                                        |
| ------------ | --------- | --------------- | -------------------------------------------------------------------------------- |
| TCP          | 80 or 443 | test target     | HTTP or HTTPS (defaults); test target may redirect to a different destination(s) |

Typically, a request using HTTP to port 80 is redirected to the HTTPS service on port 443.

#### Page Load and Transaction

Normally, for Page Load and Transaction tests (a.k.a. Browser-based tests) allowing the agent to access all destinations using HTTP and HTTPS is the easiest way to configure the ruleset, unless the destinations are well known and few in number.

| **Protocol** | **Port**   | **Destination**  | **Notes**                      |
| ------------ | ---------- | ---------------- | ------------------------------ |
| TCP          | 80 and 443 | all destinations | HTTP and HTTPS (default ports) |

Note that when an agent running browser-based tests is configured to use a proxy server, some amount of HTTP-based communication cannot be proxied. Specifically, HTTP-based downloads of SSL/TLS digital certificates (AIA fetching) and certificate revocation lists (CRLs) as well as the Online Certificate Status Protocol (OCSP) are not currently proxy-aware. Under certain circumstances (OCSP stapling unavailable, sites using EV certificates) a Browser-based test could experience errors if the agent cannot perform these types of communication directly. In this situation, two options exist:

* Create a firewall rule or ACL which permits HTTP connections (typically using the `http://` scheme) from the agent to the site required
* Create a firewall rule or ACL which responds with a TCP reset to the connection attempts from the agent

Contact ThousandEyes Customer Engineering for additional information.

#### FTP Server

FTP Server tests can use one of three TCP-based protocols: FTP (Active or Passive modes), FTPS or SFTP. The FTP server test uses the following ports by default:

* Port 21 if the test target is configured with the ftp\:// scheme, and port 20 (inbound to the agent from the target server) if Active mode is configured in the Advanced Settings tab
* Port 990 if configured with the ftps\:// scheme
* Port 22 if configured with the sftp\:// scheme

If a non-default port number is used by the target server, use that port number in the rule.

| **Protocol** | **Port** | **Destination**  | **Notes**                           |
| ------------ | -------- | ---------------- | ----------------------------------- |
| TCP          | 21       | test target      | FTP command channel                 |
| TCP          | 20       | Enterprise Agent | FTP data channel (Active mode only) |
| TCP          | 990      | test target      | FTPS                                |
| TCP          | 22       | test target      | SFTP                                |

### Voice Layer

Voice Layer provide tests for control and data streams of a voice-over-IP (VoIP) call, using SIP and RTP, respectively. The SIP Server test connects to a server, proxy, session border controller (SBC) or gateway, on the customer's premises or in the cloud. The RTP Stream test is performed between two ThousandEyes Agents to assess the quality of voice data given the characteristics of the network path.

#### SIP Server

SIP Server tests default to TCP as the protocol and 5060 as the port number. Alternatively, if UDP is selected in the **Protocol** field on the Basic Configuration tab of the test settings then use UDP, or if TLS is selected in the **Protocol** field then use TCP as the protocol and 5061 as the port number. If a different port number is used in the test, use that port number in the rule.

| **Protocol** | **Port** | **Destination**      | **Notes**                |
| ------------ | -------- | -------------------- | ------------------------ |
| TCP or UDP   | 5060     | SIP server/proxy/SBC | SIP Server test          |
| TCP          | 5061     | SIP server/proxy/SBC | SIP Server test over TLS |

Select one of the two rules above per your test's configuration.

#### RTP Stream

The RTP Stream test is performed between two ThousandEyes Agents--similar to an agent-to-agent test. Review the [requirements for agent-to-agent test rules](#agent-to-agent). RTP Stream tests default to 49152 as the port number. If a different port number is used in the test, use that port number in the rule.

| **Protocol** | **Port** | **Destination**           | **Notes**       |
| ------------ | -------- | ------------------------- | --------------- |
| UDP          | 49152    | Cloud or Enterprise Agent | RTP Stream test |

## Miscellaneous

Enterprise Agents may require additional rules for optional configurations, such as Kerberos/Active Directory authentication, proxy server configurations, or the Device Layer.

### Kerberos and Active Directory

Enterprise Agents which use Kerberos authentication (which is used by Microsoft's Active Directory) to authenticate HTTP requests to web servers or proxies must be able to reach the Kerberos domain controller (KDC) listed in the configuration's **KDC Host** field on the [Kerberos Settings page](https://app.thousandeyes.com/network-app-synthetics/agent-settings/enterprise/?section=kerberos). If using a Kerberos configuration for an agent, and if communication to the Kerberos domain controller traverses a firewall, then the following rule is required:

| **Protocol** | **Port** | **Destination** | **Notes**                  |
| ------------ | -------- | --------------- | -------------------------- |
| UDP and TCP  | 88       | KDC             | Kerberos/AD authentication |

The Kerberos settings default to port number 88. If a different port number is used in the configuration's **KDC Port** field then use that port number in the rule.

### Proxies

Enterprise Agents can be configured to use one or more proxy servers for tests, administrative communications, or both. These configurations may require additional firewall rules or ACLs.

#### Proxy Servers

An organization's proxy servers may be deployed on the same internal networks as Enterprise Agents, or the proxies may be cloud-based, including SaaS-based proxy solutions. If communication to any configured proxy server traverses a firewall, then the following rule is required:

| **Protocol** | **Port**      | **Destination** | **Notes**                   |
| ------------ | ------------- | --------------- | --------------------------- |
| TCP          | proxy port(s) | proxy server(s) | One or more ports per proxy |

A proxy server may use one port number for all connections or may use multiple ports for different protocols--most commonly one port for HTTP connections and a second for HTTPS connections. Review your organization's proxy configuration documentation or contact your proxy server administrators to determine what port(s) are used by all proxies that the agent will use.

#### PAC file Servers

When a client such as a browser or an Enterprise Agent must use multiple proxy servers (for redundancy, optimal performance or other reasons), the client can be configured to use a proxy auto-configuration (PAC) file to select a proxy to handle each HTTP request. The PAC file must be retrieved from a web server at client start-up. If communication to the PAC file's web server traverses a firewall, then the following rule is required:

| **Protocol** | **Port**  | **Destination**  | **Notes**                     |
| ------------ | --------- | ---------------- | ----------------------------- |
| TCP          | 80 or 443 | all destinations | HTTP or HTTPS (default ports) |

Select the appropriate port number based on the scheme (`http://` or `https://`) of the PAC file's URL.

### Device Layer

ThousandEyes Device Layer feature uses the Simple Network Management Protocol (SNMP) to communicate with networked devices. Agents send SNMP GET requests to networked devices either when configured as the targets of Device Discovery, or after the devices have been discovered. If communication to the targeted device traverses a firewall, then the following rule is required:

| **Protocol** | **Port** | **Destination** | **Notes** |
| ------------ | -------- | --------------- | --------- |
| UDP          | 161      | target device   | SNMP GET  |

Additional devices may be discovered without explicitly specifying an IP address in a discovery's **Targets** field. The discovery can occur even if those devices are blocked from the agent by a firewall, but the agent will not be able to retrieve data. For those discovered devices, a similar rule to the above will be required, using the discovered device:

| **Protocol** | **Port** | **Destination**   | **Notes** |
| ------------ | -------- | ----------------- | --------- |
| UDP          | 161      | discovered device | SNMP GET  |

### Internet Insights

ThousandEyes' Internet Insights feature aggregates data from existing tests of various types. Because no tests are specific to Internet Insights, no firewall rules or ACLs are required to use Internet Insights.


# Enterprise Agent Port Forwarding

When an Enterprise Agent is installed in a virtual machine as either a Virtual Appliance or a Linux package Enterprise Agent, ThousandEyes recommends configuring the virtual machine with a bridged virtual network adapter. Bridged adapters allow the agent to communicate directly with the local physical network. However, some circumstances may prevent customers from using bridged adapters. Reasons a bridged adapter may fail include lack of DHCP service for the virtual machine or security features of at the media access layer such as port-based MAC address security or wireless connections that permit only a single MAC address.

Under those circumstances, a NAT virtual adapter may be used for the Enterprise Agent. NAT adapters use an IP address and MAC address of the virtual machine's host. However, in order to permit network traffic initiated from other sources to the Enterprise Agent, port forwarding configuration within the hypervisor software will be required.

In this article we provide a port forwarding configuration in the free hypervisor [Oracle VirtualBox](https://www.virtualbox.org/) (a similar configuration can be replicated in any hypervisor supporting NAT adapters and port forwarding). Port forwarding creates a mapping from a TCP or UDP port on the virtual machine's host to a port on the Enterprise Agent's virtual machine, allowing TCP and UCP packets initiated inbound to the agent.

## Configuring port forwarding in VirtualBox

The steps below provide a basic port forwarding configuration for TCP and UDP communication to a ThousandEyes Virtual Appliance. Please note that because the ICMP protocol does not have port numbers, ICMP is not supported as an inbound protocol to the Enterprise Agent. ThousandEyes tests which use the ICMP protocol will not be able to target an Enterprise Agent using the following configuration, which uses the virtual machine host's IP address as the NAT IP address. For inbound ICMP to an Enterprise Agent (as opposed to ICMP communication which the agent initiates), the host's IP address cannot be used. Instead, a separate IP address will be required.

Also note that port forwarding using the virtual machine host's port numbers below 1024 (so-called "privileged ports") may not work with your host's operating system. In our example below, we use only host ports above 1024.

For additional information on configuration or limitations, consult the VirtualBox [Networking documentation](https://www.virtualbox.org/manual/ch06.html).

1. Run VirtualBox, highlight your agent's virtual machine and click the Settings icon.

   ![](/files/-M5xtOaBD6A7xofEQ_F_)
2. Select the Network settings. For "Adapter 1" configure the network adapter as **NAT.**

   ![](/files/-M5xtOaDB7xVUjEllqEU)
3. Click the **Port Forwarding** button, then click the **+** icon to add a port forwarding rule. Repeat the click to add more rules.

   In the example below, we have added the following rules:

   Rule 1 forwards the host port 8080/TCP to the agent port 80 for the Virtual Appliance web admin console.\
   Rule 2 forwards the host port 1234/TCP to the agent port 22 for SSH logins.\
   Rule 3 forwards the host port 49152/UDP to the agent port 49152 for a ThousandEyes Voice Layer test.\
   Rule 4 forwards the host port 49153/TCP to the agent port 49153 for a ThousandEyes agent-to-agent test using TCP.\
   Rule 5 forwards the host port 49153/UDP to the agent port 49153 for a ThousandEyes agent-to-agent test using UDP.

   Click the **OK** button when finished.

   ![](/files/-M5xtOaF4dSBBv2Fdq0W)
4. To test the configuration, using a web browser go to `https://localhost:8080/` in order to access the agent's web administration console.

   ![](/files/-M5xtOaLb2y7GWUYPw_1)

   For more information about port numbers used by ThousandEyes Enterprise Agents for tests and other functions, see [Firewall Configuration for Enterprise Agents](https://docs.thousandeyes.com/product-documentation/enterprise-agents/firewall-configuration-for-enterprise-agents).


# Security Policy and Public NTP Servers on Enterprise Agents

ThousandEyes Enterprise Agents require a source of accurate time in order to provide the correct timestamps on collected data. Accurate time is provided by configuring an Enterprise Agent to use one or more Network Time Protocol (NTP) servers. By default, the ThousandEyes Appliance (Virtual Appliance and Physical Appliance) is configured to use publicly available NTP servers provided by the [NTP Pool Project](https://www.ntppool.org/) (e.g. "0.ubuntu.pool.ntp.org"). Linux distributions used to host the Enterprise Agent Linux package may also have default public NTP servers configured.

For customers with heightened security requirements, use of a public or 3rd-party service such as the NTP Pool Project's servers may not be acceptable. To meet those requirements, the Enterprise Agents should use the organization's own NTP servers. Organizations with such requirements typically provide internal NTP resources, given that other commonly used tools such as logging or security information and event management (SIEM) software also require highly accurate timestamps. Microsoft Active Directory servers usually provide NTP services, and internet service providers (ISPs) typically include NTP time synchronization in their service offering. Customers installing Enterprise Agents in highly secure environments should consult with their Information Security or Network teams to determine a source of time via NTP which meets the organization's security policies.

Note that use of the default configuration of NTP Pool Project servers does not produce a static set of servers. Rather, the servers used will typically change over time, within a given set of servers. See the [How do I use pool.ntp.org?](https://www.ntppool.org/use.html) section of the NTP Pool Project website for more details. Customers may configure an Enterprise Agent using IP addresses rather than DNS domain names, but this approach does counteract the NTP Pool Project's policy to distribute load across the servers which have been donated to the project (the Project does not own the majority of NTP servers, but rather uses servers volunteered by other parties--servers which may provide other, unrelated services). ThousandEyes recommends using an organization's own resources or that of a trusted 3rd-party (such as the organization's ISP) if the guidelines of the NTP Pool Project are not acceptable.


# Secure Access to ThousandEyes Appliances

Management of the ThousandEyes Virtual Appliance and Physical Appliance is done using a web-based management interface. Connections to the management interface are secured with the Transport Layer Security (TLS) protocol, as indicated by the https in the URL used to access the interface. HTTPS/TLS encrypts the network connection between browser and Appliance, guaranteeing data privacy and data integrity. Additionally, TLS provides a mechanism for the user to verify the identity of the server. Many organizations' security policies require that web-based management be done using a TLS connection.

In order to access an Appliance using TLS, configuration of the Appliance, the user's browser, or both is required, depending on the level of security required. This article explains how to access the Appliance in the default configuration, how to replace the default configuration by configuring the Appliance's web server with a digital certificate, and lists steps that may be required after configuring the Appliance with a digital certificate.

## Accessing the Appliance with the Default Configuration

The web management interface of the ThousandEyes Virtual Appliance or Physical Appliance are accessed by an https URL. Access via http URL will be redirected to the HTTPS. For initial configuration, the HTTPS connection to the web interface is done using the Appliance's IP address, for example, <https://192.168.1.100>.

![](/files/-M5xtPbBYavqUgAARQpC)

Normally, accessing the Appliance web interface with the IP address will cause most browsers to generate a security warning because the pre-installed digital certificate used by the Appliance's web server is a self-signed certificate. Chrome, for example, displays the message **NET::ERR\_CERT\_AUTHORITY\_INVALID**, indicating that the certificate authority (itself) is not acceptable as an issuer of trusted root certificates:

![](/files/-M5xtPbD2Nh51b1n6sy5)

Other browsers will display similar warnings.

For the first connection to the Appliance, users must allow the browser to continue to the site. In the example above using Chrome, clicking the **Advanced** button displays a link that allows the user to proceed to the site. Other browsers may display similar buttons, or request explicit exemption be made for the site.

For customers planning to add a valid server certificate, temporarily bypassing the warning will suffice. For customers who wish to use the self-signed certificate indefinitely, configuring the user's browser with a permanent exemption may be desirable. Consult your organization's security polices, and browser's documentation or contact ThousandEyes Customer Engineering if needed, to allow the browser to proceed to the Appliance login page.

Once the browser has permitted a connection to the site, the login page for the web management will appear, likely with the browser displaying additional warnings, such as Chrome, below, displaying Not Secure in the address bar:

![](/files/-M5xtPbFT2qyR8ajidvq)

Users may now log in to the Appliance's web management with the default username ("admin") and password ("welcome"). Depending on the type of browser and configuration settings, the warnings may or may not reappear upon subsequent connections, while the Appliance uses its default self-signed certificate. Additionally, users should remove any browser exceptions for bypassing certificate warnings once they are not needed.

**IMPORTANT:** Because the initial connection will be made in a way that does not utilize the HTTPS ability to verify the server identity, initial configuration should be done in a secure environment. The Appliance should not be accessible from the public Internet for initial configuration. Organizations with stringent security requirements may wish to perform initial configuration in an isolated network, such as a virtual network or "host-only" network created within a hypervisor or similar virtualization software.

**NOTE:** The username will always be "admin" but the Appliance will require a password change when the initial configuration of the Appliance is done.

## Configuring the Appliance with a Valid Server Certificate

Valid server certificates are those issued (or "signed") by certificate authorities (CAs) that browsers trust. To obtain a valid server certificate from a CA, a certificate signing request (CSR) must be created then submitted to the CA. Upon receiving a CSR, a CA will determine whether to issue a certificate based on the requestor providing proof of identity and other factors. Once the CA creates and signs the certificate, the certificate is issued to the requestor. Many [public certificate authorities](https://ccadb-public.secure.force.com/mozilla/CACertificatesInFirefoxReport) provide this service for a fee or for free. Additionally, some organizations run their own certificate authority for private use. Consult your network or security administrator for your organization's policies on TLS certificate issuance for web servers.

The ThousandEyes Appliance provides two methods for configuring a server certificate, both of which require an external (public or private) certificate authority:

* Uploading a certificate and private key created without using the Appliance web interface.
* Creating and downloading a CSR using the web interface, then uploading the certificate via the web interface.

The Appliance does not currently support creation of a CSR by uploading a public and private key pair generated independently from the web interface.

### Uploading a Certificate and Private Key

If users wish to perform all tasks in the certificate issuance process without using the Appliance's web interface, then users can simply upload the certificate and its associated private key via the web interface. The certificate and private key must be in separate files, in [PEM format](https://docs.thousandeyes.com/product-documentation/enterprise-agents/installing-ca-certificates-on-enterprise-agents). If the server certificate requires one or more intermediate certificates to be bundled, then concatenate all certificates in PEM format into a single file, with the server certificate first, followed by the intermediate certificate that issued the server certificate. If more than one intermediate certificate is present in the chain of trust, place the first intermediate certificate (the intermediate that issued the server certificate) after the server certificate, then the second intermediate after the first.

To upload the file with the certificate(s) and the associated private key, use the following procedure:

1. Log into the Appliance web interface Use **https\://\<IP\_address\_of\_Appliance>** in a web browser, and continue through any security warnings, as described in the section *Accessing the Appliance with the Default Configuration*.
2. Click **SSL Settings** in the menu at left.
3. Click **Import Private Key**.
4. Navigate to the private key file on the local computer using the file browser, and select the file
5. If the certificate is protected with a passphase, enter the phrase in the **Passphrase** field; otherwise leave the field blank.
6. Click **Import Certificate**.
7. Navigate to the certificate file on the local computer using the file browser, and select the file
8. Click **Submit SSL Certificate**.

Installing the certificate requires rebooting the Appliance. A modal will appear, asking whether the user wants to reboot the appliance now. After rebooting, the **Installed SSL Certificate** section now displays information about the installed server certificate.

### Creating a CSR in the Web Interface

In the Appliance web interface, users can create and download a CSR and then use that CSR to obtain the server certificate, and then upload the certificate. If the server certificate requires one or more intermediate certificates to be bundled, then concatenate all certificates in PEM format into a single file, with the server certificate first, followed by the intermediate certificate that issued the previous certificate.

The Appliance generates and retains the corresponding private key as long as the CSR that generated the private key is active in the web interface.

Consult your network or CA administrator for more information on the values needed for generating a CSR.

To create a CSR in the Appliance's web interface, use the following procedure:

1. Log into the Appliance web interface Use **https\://\<IP\_address\_of\_Appliance>** in a web browser, and continue through any security warnings, as described in the section *Accessing the Appliance with the Default Configuration*.
2. Click **SSL Settings** in the menu at left.
3. Fill out the fields in **Generate CSR** form\
   Fields with a red \* are required.

   **NOTE:** Subject Alternative Names is not a required field, but if left blank be certain that:

   * The Common Name field contains a domain name, if required for access AND
   * Your CA will populate the SAN field with the value of the Common Name OR
   * Your certificate issuance process includes adding SAN values (domain names, hostnames and/or IP addresses) subsequent to the CSR generation, via CSR request attributes
4. Click **Create CSR**.

The SSL Settings page will now display the CSR's configuration in the **Outstanding CSR** field. A private key associated with this CSR has been generated and will be stored until either a certificate with the associated public key is uploaded, or the pending CSR is deleted.

Once the certificate is created, place the certificate file in [PEM format](https://docs.thousandeyes.com/product-documentation/enterprise-agents/installing-ca-certificates-on-enterprise-agents) on the local computer, then upload the certificate to the Appliance using the following procedure:

1. Log into the Appliance web interface.
2. Click the SSL Settings section in the menu at left
3. Click **Import Certificate**.
4. Navigate to the certificate file on the local computer using the file browser, and select the file
5. Click **Submit SSL Certificate**.

Installing the certificate requires rebooting the Appliance. A modal will appear, asking whether the user wants to reboot the appliance now. After rebooting, the **Installed SSL Certificate** section now displays information about the installed server certificate.

## Accessing the Appliance with a Valid Certificate

Once a valid server certificate has been Installed, the Appliance can be accessed with an https\:// URL using any of the names (or IP addresses) in the Subject Alternative Names field. For example, if the CSR form in the Appliance contained:

![](/files/-M5xtPbTbMMobZRKUZVj)

then a browser could use the following URLs securely:

<https://test.stg.thousandeyes.com>\
<https://test-teva.stg.thousandeyes.com>\
<https://10.1.1.100>\
<https://192.167.150.100>

**NOTE:** To use names such as test.stg.thousandeyes.com in URLs, the browser must be able to resolve the name to an IP address through DNS, local host files or some other name resolution service. Consult your network administrator to ensure that names chosen for your certificate have the necessary configuration in your organization's name service.

## Deleting a Certificate or CSR

Once a certificate is uploaded, the certificate and its associated private key can be removed by clicking **Remove Certificate**.

![](/files/-M5xtPbXCKYkO8TGcIED)

Removing the certificate requires rebooting the Appliance. A modal will appear, asking whether the user wants to reboot the appliance now. Upon rebooting, the Appliance will automatically re-install the original, self-signed certificate.

Additionally, a new certificate can be uploaded to replace a previously uploaded certificate. The Appliance will always retain the original, self-signed certificate regardless of the number of user-uploaded certificates.

Once a CSR is created, removing the current CSR can be done by clicking the red X in the Outstanding CSR field. The associated private key is also removed.


# Disabling the Web Server of a Virtual Appliance

ThousandEyes’ Virtual Appliance is normally managed remotely via a web-based administration tool served from the Virtual Appliance, and accessed with a URL of **http\://\<IP\_address\_of\_the\_appliance>**. If an organization’s security policy or other factors require that the Virtual Appliance not run its web server, then the web server can be disabled, and the Virtual Appliance managed remotely via SSH using the VA’s command line interface (CLI).

## Prerequisites

SSH access to the Virtual Appliance is required both to disable the web server and to manage the Virtual Appliance after the web server is disabled. To configure SSH access to the Virtual Appliance, consult the following articles:

* [Connecting to the ThousandEyes Virtual Appliance using SSH (Windows)](https://docs.thousandeyes.com/product-documentation/enterprise-agents/connecting-to-the-thousandeyes-virtual-appliance-using-ssh-windows)
* [Connecting to the ThousandEyes Virtual Appliance using SSH (Mac/Linux)](https://docs.thousandeyes.com/product-documentation/enterprise-agents/connecting-to-the-thousandeyes-virtual-appliance-using-ssh-mac-linux)

**NOTE:** After disabling the web server, the only method for management of most settings on the Virtual Appliance is through SSH access, which requires that at least one public key be uploaded to the Virtual Appliance. If the private key corresponding to the SSH public key on the Virtual Appliance is lost, access (and the ability to configure the Virtual Appliance) is lost. ThousandEyes recommends the following, prior to disabling the web server:

1. Multiple SSH public keys be loaded on the Virtual Appliance
2. Access is verified using each of the private-public key pairs
3. The private keys are stored in a secure location which will not be forgotten or lost

## Disabling the web server

To disable the web interface in the Virtual Appliance:

1. Access the Virtual Appliance CLI through SSH
2. Execute the command sudo te-va-disable-webserver

## Enabling the web server

To enable the web interface in the Virtual Appliance:

1. Access the Virtual Appliance CLI through SSH
2. Execute the command sudo te-va-enable-webserver


# NAT Traversal for Agent-to-Agent Tests

An agent-to-agent test permits ThousandEyes users to monitor two endpoints and visualize the network path in both directions, which can mean faster, more accurate identification of problems than with an agent-to-server test. However, unlike an agent-to-server test, where the test target is typically intended to receive network traffic initiated by other hosts, in an agent-to-agent test often one or both agents cannot receive network traffic initiated by other hosts, either from the public Internet or from other network locations. Changes to network address translation (NAT), port address translation (PAT) and/or stateful packet filter (SPF, i.e. firewall) rules would normally be required to allow the test traffic.

To avoid the need for changes, ThousandEyes provides a NAT traversal feature, which allows the agent-to-agent test traffic to work in conjunction with typical NAT/PAT/SPF configurations. NAT traversal in the ThousandEyes platform is implemented through a proprietary method similar to NAT traversal methods described in IETF standards such as RFC 5382. Agents behind NAT devices will register with the ThousandEyes NAT traversal server in order to discover the agents’ NAT and PAT characteristics, then use the discovered information when performing agent-to-agent tests.

## When to Use NAT Traversal

If an agent-to-agent test fails with an error indicating that one or both agents cannot reach the opposite agent, NAT traversal is likely to be required. An agent requires NAT traversal if the following are true:

1. The Enterprise Agent is behind a NAT and/or PAT device

   Check the Agent Settings of the Enterprise Agent. If a Private IP address is present, the agent is behind a NAT, and will likely need NAT traversal for agent-to-agent tests. Port address translation will normally be done in conjunction with network address translation. Stand-alone port address translation is less common, but if you are port forwarding a public port to a different private port, then you will also need NAT traversal.
2. Inbound communication to the agent is blocked

   Your firewall/NAT device prevents communications initiated from the public Internet to the Enterprise Agent, and only allows the agent to initiate communications outbound to destinations on the public Internet.
3. Test **Direction** configuration

![](/files/-M62_WncFRiIOAyg43cE)

* The **Direction** selector on the agent-to-agent test is “Both Directions”, and the above two conditions are true for one or both Enterprise Agents
* The **Direction** selector is “Source to Target” and the above two conditions are true for the Target Enterprise Agent
* The **Direction** selector is “Target to Source” and the above two conditions are true for the Source Enterprise Agent

## Configuring NAT Traversal

Configure the NAT traversal feature by checking the **Behind a NAT** box under the agent's **Advanced Settings** tab on the **Network & App Synthetics > Agent Settings > Enterprise Agents** page.

![](/files/-M62_WnhNRQ2idHHFdiW)

**NOTE:** Because the NAT traversal feature is set on a per-agent basis (rather than a per-test basis) the NAT traversal feature will affect all agent-to-agent tests in which the agent participates.

### Compatibility Check

When configured for NAT traversal, an Enterprise Agent will perform a NAT traversal compatibility check every five minutes, beginning when the agent contacts the ThousandEyes collector the first time after the **Behind a NAT** box on the Agent Settings is checked.

Note that the agent will contact the collector once per minute, and must first download the new configuration, perform the check and then wait for the next contact with the collector to upload results of the compatibility check. Thus, the results of the initial check may require up to two minutes to be displayed.

If the compatibility check determines that NAT traversal will not work for a particular agent, the check displays an error on the **Agent Settings** page, indicated by a red triangle icon, along with the following message:

**NAT Issues: NAT traversal not supported**

If the check fails, consult the requirements for NAT traversal in the following section.

## NAT Traversal Requirements

The requirements for NAT traversal to function properly are listed below.

1. Agent can contact ThousandEyes’ NAT traversal server

   Ensure that the agents can initiate outbound connections to **ntrav.thousandeyes.com** on destination TCP ports 9119 and 9120 when TCP is chosen as the protocol in the agent-to-agent test, and on TCP and UDP ports 9119 and 9120 when UDP is chosen.

   Failure of an agent to contact the ThousandEyes NAT traversal server will result in a test error message:

   **Failed to negotiate NAT traversal with (source/target) agent**
2. NAT is not symmetric

   Symmetric NAT is an implementation of NAT in which outbound packets from the translated device a) have port address translation performed on the source ports, and b) the translated source port number is not constant for different destination IP address/port pairs (see [RFC 5382](https://tools.ietf.org/html/rfc5382) for formal definitions of types of NAT).

   For example, a client sends packets from source port 10000 to a server on port 80. The client’s firewall translates the source port to 50000. Immediately thereafter, the client sends packets from source port 10000 to another server (different IP address) on port 80. The firewall translates the source port to 50001. The NAT is symmetric, and will not work with NAT traversal.

   Symmetric NAT of an Enterprise Agent’s communication will result in a test error message:

   **Connection to (source/target) agent failed**
3. Firewall/NAT device(s) honor TCP keep-alives

   An agent configured to use NAT traversal registers with the ThousandEyes NAT traversal server using a long-lived TCP connection. The connection is kept open indefinitely using TCP keep-alives. This is done because the public port of this TCP connection is part of the registration data, and is given to other agents in order to send inbound agent-to-agent test traffic. The inbound test traffic uses the public port as the test traffic’s destination port (see the following requirement for TCP simultaneous open). If long-lived connections were not used, then it is possible that the public port would change over time. We do not want the public port number to change, since a change would be disruptive to the test, hence the requirement to support long-lived TCP connections.

   Most firewall and NAT devices will honor keep-alives. If NAT traversal fails, check your firewall or other NAT device to see if there are hard limits on the length of time a TCP connection can be maintained. Of course, reboots or other actions that clear the NAT and/or state tables of firewalls or NAT devices can disrupt a connection between agent and ThousandEyes NAT traversal server, as well.

   Failure of a firewall/NAT device to honor TCP keep-alives will result in a test error message:

   **Failed to negotiate NAT traversal with (source/target) agent**
4. Firewall/NAT device(s) support TCP simultaneous open (TCP-based tests only)

   When an agent-to-agent test uses TCP, the NAT traversal feature makes use of a TCP state called “simultaneous open”, which replaces the more common “three-way handshake” sequence of three packets (SYN packet sent, SYN-ACK received, ACK sent) with a four-packet sequence (SYN packet sent, SYN-ACK received on both ends). This allows both agents to initiate inbound traffic using the public port discovered in the registration with the NAT traversal server.

   Most firewall and NAT devices support TCP simultaneous open. NAT/firewall devices that do not support TCP simultaneous open will not work with NAT traversal for TCP-based agent-to-agent tests. UDP-based agent-to-agent tests do not have this requirement.

   Firewall/NAT devices that do not support TCP simultaneous open will result in a test error message:

   **Connection to (source/target) agent failed**
5. When using NAT on a target server via UDP, the target agent must have a public IP configured **and** that address must be what the platform uses for NAT traversal. During the NAT UDP test initialization, both agents will send packets to the ThousandEyes NAT traversal server. The server then examines the packets to determine which IP addresses to tell the agents to use. If an agent only has a private IP and is the target of the test (such as an agent-to-agent or RTP stream test using UDP), the ThousandEyes NAT traversal server will not provide the private IP of the packets it received to the source agent.

   **Verify the Public IP:** On the target Enterprise Agent, open **Network & App Synthetics > Agent Settings**, select the agent, then **System Information** and the **Network Information** tab. Confirm that the **Public IP** shown there is correct and reachable for UDP NAT traversal.

   This is expected behavior, and means that you cannot target an Enterprise Agent behind a NAT that does not have a public IP address using UDP.

## Troubleshooting

### Private IP Shown as the Test Target (NAT-Enabled Enterprise Agent)

Occasionally the ThousandEyes platform might display a private IP as the target for a test while that test's **Views > Path Visualization** still shows traffic toward the NAT-enabled agent. (That is, NAT is working, but the target IP in Views looks incorrect.) To resolve this issue, try the following changes to the Enterprise Agent:

1. In **Agent Settings**, clear the **Behind a NAT** checkbox.
2. In the **IP Address or Hostname** field that then appears, enter the agent's public IP manually. Then click **Save Changes**.
3. Re-enable **Behind a NAT**, then save again.
4. Re-run the test and confirm the target IP in the test views.

### Failed NAT Traversal Compatibility Check

If an Enterprise Agent fails its NAT traversal compatibility check, or your agent-to-agent test fails to return data in one or both directions even when NAT traversal is configured on both Enterprise Agents, please check your firewall or NAT device logs for packets to the agent IP address and port configured for the agent-to-agent test, then contact the Customer Engineering team via email (<support@thousandeyes.com>) or via our in-app live support chat.

## Additional Information

Consult the following RFC documents for additional background on NAT traversal:

1. [Network Address Translation (NAT) Behavioral Requirements for Unicast UDP](https://tools.ietf.org/html/rfc4787)
2. [Network Address Translation (NAT) Behavioral Requirements for TCP](https://tools.ietf.org/html/rfc5382)
3. [Session Traversal Utilities for NAT (STUN)](https://tools.ietf.org/html/rfc5389)


# Enterprise Agent on Docker Advanced Networking

The default Enterprise Agent installation on Docker uses NAT to connect the agent to the network using the host's IP address. A NATted connection gives the enterprise agent sufficient connectivity to the host's network for all measurements, however, advanced users may desire different types of network connectivity between the enterprise agent container and their network.

## NAT

![](/files/-M5xtNfnlEV8puV6KDuk)

The default installation connects the agent to host's internal *docker0* bridge. docker0 bridge is not bridged with any of the external interfaces, i.e. *eth0*. NAT is performed between docker0 bridge (inside) and host's default external interface, i.e. *eth0* (outside).

No further configuration is required to run the enterprise agent container in NAT mode.

### Host with Multiple Physical Interfaces

![](/files/-M5xtNfpSJhtfCMpt-v_)

What happens if we have a host with multiple physical interfaces, for instance *eth0* and *wlan0*? Default NAT configuration does not favor any of the interfaces, instead it relies on Kernel IP routing to choose the exit interface. You can verify default exit interface by looking for the default route in the Kernel IP routing table:

> \# route\
> Kernel IP routing table\
> Destination Gateway Genmask Flags Metric Ref Use Iface\
> **default 10.10.40.1 0.0.0.0 UG 0 0 0 eth0**\
> 10.10.40.0 \* 255.255.255.0 U 0 0 0 eth0\
> 10.10.50.0 \* 255.255.255.0 U 0 0 0 wlan0\
> 172.17.0.0 \* 255.255.0.0 U 0 0 0 docker0

What happens if you want the enterprise agent to use the Wireless connection, i.e. *wlan0* interface instead of *eth0*? You could change the default route to *wlan0*, but this will redirect all traffic from the host server.

A better solution is to change the default route for enterprise agent container only. This can be done with policy routing, or more specifically **source policy routing**:

1. Create a custom policy routing table by adding routing table id (pick a number that is not already taken, i.e. *200*) and name (i.e. *wlan0rt*) in the */etc/iproute2/rt\_tables* file.

   > echo 200 wlan0rt >> /etc/iproute2/rt\_tables
2. Source policy routing routes traffic based on source address. Enterprise agent container may change its internal IP address between host reboots with default installation and you cannot configure the agent with a static IP address when using default docker bridge. Verify which network is available on *docker0* bridge:

   > \# ifconfig\
   > docker0 Link encap:Ethernet HWaddr 02:42:64:92:ee:32\
   > inet addr:**172.17.0.1** Bcast:0.0.0.0 Mask:**255.255.0.0**\
   > \[..]

   Enterprise agent container will be attached to docker0 bridge by default so it must use an IP address from the bridge network. Write down the bridge network \\(i.e. 172.17.0.0/16\\)
3. Create a policy routing rule that instructs Kernel IP routing to use the wlan0rt routing table for all the traffic coming from *docker0* bridge network:

   > ip rule add from 172.17.0.0/16 lookup wlan0rt
4. Verify that the IP rule has been added:

   > \# ip rule list\
   > 0: from all lookup local\
   > **32765: from 172.17.0.0/16 lookup wlan0rt**\
   > 32766: from all lookup main\
   > 32767: from all lookup default
5. The last thing you need to do is add the actual rule that will route the traffic out the *wlan0* interface in the *wlan0rt* routing table:

   > ip route add default via 10.10.50.1 dev wlan0 table wlan0rt

   Note that part of the configuration is the default gateway for the network *wlan0* interface is connected to (i.e. 10.10.50.1).
6. The *ip rule* and *ip route* commands are not persistent, they will be removed upon host reboot or interface state change. To make them persistent, open /etc/network/interfaces with your favorite editor:

   > vi /etc/network/interfaces

   Find the section of the interface that we route the traffic to (i.e. *iface wlan0 inet*) and add the *ip rule* and *ip route* commands inside the interface configuration block:

   > iface wlan0 inet dhcp\
   > **post-up** ip rule add from 172.17.0.0/16 lookup wlan0rt\
   > **post-up** ip route add default via 10.10.50.1 dev wlan0 table wlan0rt

## Bridge

![](/files/-M5xtNftdOjVH0bx8qWE)

Bridged connectivity allows the enterprise agent to connect directly into user's network, using either private or public IP address. Starting with v1.12, Docker allows you to bridge the enterprise agent container with a host's physical interface using the **macvlan** network driver.

**Warning:** Some wireless NIC drivers or wireless collectors only support a single MAC address per physical wireless NIC. In that case bridge configuration will not work and you should use the NAT configuration.

### Bridging with macvlan (docker >= 1.12)

1. First you need to create a new Docker Network using the macvlan network driver. Each macvlan network requires one *parent* interface. Parent interface is a physical interface of the Docker Host to which the macvlan network will be bridged. You need to configure the subnet and the gateway of the network you are bridging into.

   **Warning:** Docker containers are assigned IP addresses from Docker's IPAM driver from the *subnet* pool you configure for the network. Enterprise agent container cannot request the IP from the external DHCP server. To avoid IP address collision, you should avoid bridging the Docker macvlan network to an existent physical network with DHCP service.

   > docker network create -d macvlan \\\
   > \--subnet=10.10.40.0/24 --gateway=10.10.40.1 \\\
   > -o parent=eth0 \\\
   > macvlan0
2. Ensure that network was created:

   > \# docker network ls
   >
   > NETWORK ID NAME DRIVER\
   > **0f4311081482 macvlan0 macvlan**
3. When utilizing the **docker run** command upon enterprise agent installation, make sure you add the *--net=macvlan0* parameter before the last line. This will connect the enterprise agent container to the macvlan network you have just created.

   > \**--net=macvlan0 \**\
   > thousandeyes/enterprise-agent /sbin/my\_init
4. Verify enterprise agent connectivity. Container should be able to ping the default gateway you have configured upon macvlan0 network creation:

   > \# docker exec -ti *\<agent-container-name>* ping -c 4 10.10.40.1
   >
   > PING 10.10.40.1 (10.10.40.1) 56(84) bytes of data.\
   > 64 bytes from 10.10.40.1: icmp\_seq=1 ttl=64 time=0.254 ms\
   > 64 bytes from 10.10.40.1: icmp\_seq=2 ttl=64 time=0.223 ms\
   > 64 bytes from 10.10.40.1: icmp\_seq=3 ttl=64 time=0.237 ms\
   > 64 bytes from 10.10.40.1: icmp\_seq=4 ttl=64 time=0.228 ms
   >
   > \--- 10.10.40.1 ping statistics ---\
   > 4 packets transmitted, 4 received, 0% packet loss, time 2997ms\
   > rtt min/avg/max/mdev = 0.223/0.235/0.254/0.019 ms


# Enterprise Agent Management

This section contains articles on how to manage your Enterprise Agents once they are installed and configured.


# Cisco Devices

This section contains articles on how to manage your Cisco device-based Enterprise Agents once they are installed and configured.


# Disable, Restart, or Uninstall the Enterprise Agent via DCNM

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

This article contains the steps to either disable, restart, or uninstall a ThousandEyes Enterprise Agent via DCNM.

{% hint style="info" %}
Enterprise Agents must be disabled before they can be uninstalled.
{% endhint %}

## Disable an Enterprise Agent

To temporarily disable a running ThousandEyes Enterprise Agent, open the **ThousandEyes Agent** drop-down menu, and select **Stop**. The status will then update:

![](/files/LLc5dSzhiXYn6RKhpwu1)

## Restart an Enterprise Agent

Once stopped, the agent can be restarted by opening the **ThousandEyes Agent** drop-down menu, and select **Start**. The status will then return to **Running**.

## Uninstall an Enterprise Agent

To uninstall an Enterprise Agent via DCNM, there are four steps:

1. [Disable the Agent](#disable-an-enterprise-agent).
2. Uninstall the Enterprise Agent from the switch.
3. Delete the identity configuration file.
4. Delete the Enterprise Agent from the ThousandEyes web app.

Step 1 is covered in an earlier section. Steps 2-4 are covered below.

### Uninstall the Enterprise Agent from the Switch

Open the **ThousandEyes Agent** drop-down menu, and select **Uninstall**. A confirmation message will pop up to confirm the choice. Click **Ok** to uninstall the agent from the switch:

![](/files/PfWCsPAxsO4m5DZKhAgf)

### Delete the Identity Configuration File

{% hint style="warning" %}
If you are replacing the existing switch with a new switch, but wish to keep the same Enterprise Agent, do not continue this process. You can reinstall the Enterprise Agent on the new switch using the existing identity configuration file. However, if you complete this step, a new Enterprise Agent will be created.
{% endhint %}

To delete the Enterprise Agent identity:

1. Click the **Play** button.

![](/files/yLCoODj48Kmr95CsC8Ea)

2. Open the drop-down list and select **ThousandEyes\_Agent\_Identity\_Delete**.

![](/files/l6AsLzROnG2o6Ro53vlY)

3. Click **Deploy** to delete the agent identity.

### Delete the Enterprise Agent from the ThousandEyes Web App

1. In the ThousandEyes web app, navigate to **Network & App Synthetics > Agent Settings**.
2. Find the desired agent, and click the three dots icon at the end of the row.
3. Select **Delete**.
4. In the pop-out panel, click **Delete** to confirm removing the agent from the ThousandEyes web app.

{% hint style="success" %}
The Enterprise Agent is now completely uninstalled and removed from ThousandEyes.
{% endhint %}


# Docker Agents


# Add/Remove BrowserBot from Existing Docker Enterprise Agents

Docker-based Enterprise Agents can be installed with or without BrowserBot included, depending on the need for browser synthetics testing within the environment. This can also be changed after the initial deployment. The two images are identified as `latest-agent` (base Enterprise Agent only), and `latest` (includes BrowserBot).

This article outlines the steps to transition an Enterprise Agent between images.

## Add BrowserBot to an Existing Docker-based Enterprise Agent

To switch from a non-BrowserBot installation to one that is set up for browser synthetics tests, you will need to run two sets of commands in the Docker container's CLI. The first set of commands are for configuring seccomp and AppArmor profiles for your Docker host.

```
curl -Os https://downloads.thousandeyes.com/bbot/configure_docker.sh
chmod +x configure_docker.sh
sudo ./configure_docker.sh
```

The second set of commands will install and setup the Enterprise Agent. Ensure that you replace the variables (`<NAME>`, `<HOST_VOL_AGENT_DIR>`, and `<TE_ACCOUNT_TOKEN>`) with your configuration requirements:

```
docker pull thousandeyes/enterprise-agent > /dev/null 2>&1
docker stop '<NAME>' > /dev/null 2>&1
docker rm '<NAME>' > /dev/null 2>&1
docker run \
  --hostname='<NAME>' \
  --memory=2g \
  --memory-swap=2g \
  --detach=true \
  --tty=true \
  --shm-size=512M \
  -e TEAGENT_ACCOUNT_TOKEN=TE_ACCOUNT_TOKEN \
  -e TEAGENT_INET=4 \
  -v '<HOST_VOL_AGENT_DIR>/thousandeyes/<NAME>/te-agent':/var/lib/te-agent \
  -v '<HOST_VOL_AGENT_DIR>/thousandeyes/<NAME>/te-browserbot':/var/lib/te-browserbot \
  -v '<HOST_VOL_AGENT_DIR>/thousandeyes/<NAME>/log/':/var/log/agent \
  --cap-add=NET_ADMIN \
  --cap-add=SYS_ADMIN \
  --name '<NAME>' \
  --restart=unless-stopped \
  --security-opt apparmor=docker_sandbox \
  --security-opt seccomp=/var/docker/configs/te-seccomp.json \
  thousandeyes/enterprise-agent /sbin/my_init
```

## Remove BrowserBot from an Existing Docker-based Enterprise Agent

To switch from a BrowserBot installation to the base agent only, run the following commands in the Docker container's CLI, ensuring that you replace the variables (`<NAME>`, `<HOST_VOL_AGENT_DIR>`, and `<TE_ACCOUNT_TOKEN>`) with your configuration requirements:

```
docker pull thousandeyes/enterprise-agent:latest-agent > /dev/null 2>&1
docker stop '<NAME>' > /dev/null 2>&1
docker rm '<NAME>' > /dev/null 2>&1
docker run \
  --hostname='<NAME>' \
  --memory=2g \
  --memory-swap=2g \
  --detach=true \
  --tty=true \
  --shm-size=512M \
  -e TEAGENT_ACCOUNT_TOKEN=<TE_ACCOUNT_TOKEN> \
  -e TEAGENT_INET=4 \
  -v '<HOST_VOL_AGENT_DIR>/thousandeyes/<NAME>/te-agent':/var/lib/te-agent \
  -v '<HOST_VOL_AGENT_DIR>/thousandeyes/<NAME>/te-browserbot':/var/lib/te-browserbot \
  -v '<HOST_VOL_AGENT_DIR>/thousandeyes/<NAME>/log/':/var/log/agent \
  --cap-add=NET_ADMIN \
  --cap-add=SYS_ADMIN \
  --name '<NAME>' \
  --restart=unless-stopped \
  --security-opt apparmor=docker_sandbox \
  --security-opt seccomp=/var/docker/configs/te-seccomp.json \
  thousandeyes/enterprise-agent:latest-agent /sbin/my_init
```


# Upgrading Operating Systems for Enterprise Agents

This article provides an overview of upgrading your operating system to a supported version for the ThousandEyes Enterprise Agent, and provides links to specific upgrade instructions for supported environments.

## Supported Operating Systems

For a full list of supported operating systems, see [Enterprise Agent System Requirements](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents).

### Support Lifecycle

As operating system providers end support for versions of their operating systems, ThousandEyes will reduce or end support for Enterprise Agents on those operating systems. For more information on the lifecycle status of supported operating systems, see [Enterprise Agent Support Lifecycle](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/enterprise-agent-support-lifecycle).

## Additional Information for Installation Types

### Linux Packages

Customers who choose to install the ThousandEyes Enterprise Agent onto their own Linux system using the **Linux Package** installation method are responsible for system maintenance.

### Docker Enterprise Agents

To ensure the internal Docker OS is up-to-date, the command sequence will be:

```
docker pull <name>
docker stop <running-agent>
docker rm <running-agent>
docker run <same options as previous launch>
```

### Cisco Application Hosting

ThousandEyes Enterprise Agents running on Cisco devices using Cisco Application Hosting are based on a Docker image, where the agent services within the running container are upgraded automatically. However, the application package which includes the container image is not. While the image is updated periodically to update the OS, address vulnerabilities and incorporate enhancements, manual intervention is required to upgrade the application to use the latest image.

{% hint style="info" %}
The agent application package that includes the container image can be upgraded without upgrading the device system software. Upgrading the agent won't affect the device.

Reloading the device is not required, as it is an in-place upgrade.
{% endhint %}

These agents can be upgraded with the `app-hosting upgrade` command, replacing **\<app-name>** with your application identifier and **\<ARCH-VERSION>** with the device architecture and the current image version.

{% hint style="info" %}
Refer to the ThousandEyes changelog for the latest CAF version and package name: [ThousandEyes Changelog](https://docs.thousandeyes.com/whats-new/changelog#cisco-application-hosting-framework-caf-version-5.1.3).
{% endhint %}

```
#app-hosting upgrade appid <app-name> package https://downloads.thousandeyes.com/enterprise-agent/thousandeyes-enterprise-agent-<ARCH-VERSION>.cisco.tar
```

{% hint style="info" %}
If the router is behind a HTTP proxy, configuring the following may allow the image to be downloaded and installed:

```
ip http client proxy-server <name> proxy-port <port>
```

{% endhint %}

{% hint style="info" %}
During the upgrade process, the agent will be stopped and deactivated. This means that any CA certificates that were added will be removed and must be reapplied. For more information on how to reapply the CA certificate, see [Installing CA Certificates on Cisco Devices](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/troubleshooting/installing-ca-certificates-on-enterprise-agents#installing-on-cisco-docker-devices)
{% endhint %}

### ThousandEyes Virtual Appliances

ThousandEyes virtual appliances are based on supported Ubuntu LTS releases. See [Supported Operating Systems - Ubuntu](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/enterprise-agent-support-lifecycle#ubuntu-linux) for more information on the specific supported Ubuntu release and support lifecycle.

For operating system upgrades, customers are responsible for upgrading the TEVA to the latest supported version. ThousandEyes will make best efforts to communicate affected customers through alerts in the ThousandEyes web application, emails to subscribers, and the [Changelog](https://docs.thousandeyes.com/whats-new/changelog).

## Replacing Enterprise Agents

ThousandEyes Enterprise Agents can be replaced, rather than upgraded, either by clustering agents, or by transferring the agent identity files.

### Agent Clustering

This method consists of deploying a new agent, clustering together the new agent with the old one, and then deleting the old agent from the cluster. The act of clustering transfers test associations and agent characteristics.

Complete instructions for replacing Enterprise Agents using the agent clustering method are available [here](https://docs.thousandeyes.com/product-documentation/enterprise-agents/replacing-an-enterprise-agent-using-the-agent-clustering-method).

### Transferring Agent Identity Files

During the installation of a replacement Enterprise Agent, identity files from an existing Enterprise Agent are transferred to the replacement system. The platform will make no distinction between the original agent and the replacement agent.

Complete instructions for replacing Enterprise Agents using agent identity files are available [here](https://docs.thousandeyes.com/product-documentation/enterprise-agents/replacing-an-enterprise-agent-using-agent-identity-files).

## Requesting Support Consultations

Some customers may use the upgrade process as an opportunity to consider new agent deployment options, such as replacing virtual machines with containers. ThousandEyes Customer Engineering is available via our [in-application chat function](https://docs.thousandeyes.com/product-documentation/getting-started/getting-support-from-thousandeyes), or via email at <support@thousandeyes.com> to answer any questions that you may have.


# Backup and Restore Your Enterprise Agent Configuration

Backup and restore options are available for Enterprise Agent configurations, in case the agent upgrade fails. In this case, you can delete the original agent, re-deploy a new agent, and restore the configuration from the backup file.

## Backup the Agent Configuration

You can backup your agent configuration prior to upgrading to the latest version of the operating system, in order to prepare for any potential failure situations that occur during the upgrade process. To back up the configuration, open the TEVA/TEPA UI, and navigate to the **Advanced Settings**:

![](/files/JSKRakyYqebpRe9pMlmu)

Click **Backup** to download the configuration. A `.backup` file will be downloaded.

## Restore a Previous Configuration

After launching the web UI for the first time, reset the default password. You will then be directed to the Agent menu screen, and offered two options for the Agent Identity. The default selection is **New ID**, which accepts the registration by typing in Account Group Token.

![](/files/7RSOxNS2pNXgvH7dv05g)

To restore from a previous configuration, select **Restore from backup**, and upload the previously saved `.backup` file:

![](/files/SdxKWrcJTWw8Hb6PTAyJ)

After uploading the file, click **Continue**, and the restoration will initiate, automatically registering the new agent with the original agent’s identity and inherited agent ID, as well as any test assignments and configurations.


# Crash Reporting for Enterprise Agents

In order to improve diagnosis of problems with Enterprise Agents, ThousandEyes has added a crash report feature. Similar to other common programs and operating systems which send reports to their parent companies when execution is halted by an error, this feature allows Enterprise Agents to send error data to ThousandEyes when the te-agent process encounters a fatal error.

When an error occurs and a crash report is generated, the data is uploaded automatically—no user interaction or configuration is required for this feature to function, other than allowing outbound access from the Enterprise Agent to the URL `https://crashreports.thousandeyes.com`. Many customers will already have firewall rules permitting general outbound HTTPS access. Alternatively, customers may have already enabled HTTPS access to 75.2.49.1 and 99.83.242.129 for the standard communication between Enterprise Agents and ThousandEyes. Either of these firewall rules will cover crashreports.thousandeyes.com. To further narrow your firewall rule down to a single host, simply perform DNS resolution on crashreports.thousandeyes.com with a tool such as `dig` or `nslookup`, or `ping crashreports.thousandeyes.com.`; For customers behind web proxies, the crash reporting feature will employ your Agent’s existing proxy configuration.

Crash reports are typically on the order of 1 megabyte in size, so should not create problems consuming bandwidth or similar resources. Data sent contains no sensitive information pertaining to customer test data or configuration.

This binary file can be inspected with crash report parsers which accept .dmp formatted reports, a generic tool such as `od` or similar binary file editors, or an online crash report parser such as <http://www.osronline.com/>.

In general, this feature should have minimal or no impact on customers. This feature is currently enabled automatically and not user-configurable.


# Configuring a Local Mirror of the ThousandEyes Package Repository

Customers may need to create a local copy of the ThousandEyes Linux package repositories used by ThousandEyes Enterprise Agents for reasons such as change control or security requirements. This document outlines the requirements and processes to create a local repository mirror containing packages required by the ThousandEyes Enterprise Agents, and to modify ThousandEyes Enterprise Agents to update from the local mirror.

Depending on the type of Linux operating system on which your Enterprise Agents run, you will need to create a Red Hat repository, an Ubuntu repository or both. Mirroring the ThousandEyes repository requires sufficient storage, along with permissions to install software. The Red Hat repository requires at minimum 100 GB storage and the Ubuntu repository requires at minimum 10 GB storage.

**NOTE**: ThousandEyes Enterprise Agents should run current versions of ThousandEyes packages. If the Agent cannot update because of failure to reach the mirrored repository or with the repository failing to provide current package versions, then there is risk that certain features of the Enterprise Agent will not work as advertised. Use this process at your own risk.

## Configure a Server for the Repository

This document provides installation and configuration instructions on a Red Hat Enterprise Linux (RHEL) version 7 server operating system and on an Ubuntu 16.04 server operating system. Other operating systems can be used; consult your operating system documentation to determine what comparable commands are needed for the steps listed below, or contact the ThousandEyes Customer Engineering team.

Don’t be confused: a server running any type of operating system can host either Red Hat or Ubuntu repositories or both. In general, however, we recommend using the same Linux distribution for your server’s operating system as the type of repository, if possible.

General system administration tasks for the server, such as application of updates and patches, are out of scope for this document. Consult your operating system documentation.

### Determine Which Type(s) of Repository to Create

Customers using any type of ThousandEyes Appliance should create an Ubuntu mirror. This includes Virtual Appliances, Hyper-V Appliances, and the Physical Appliance.

Customers with Enterprise Agents installed via Linux package or Docker container should create mirror types that are the same as the Linux distribution used for the Enterprise Agent (Alpine Linux).

To determine which type(s) of Enterprise Agents are used in your organization, review the listing of your Enterprise Agents from the Enterprise Agents page in the ThousandEyes platform. Enterprise Agent operating systems are listed in the General Info box:

![](/files/-M5xtNL1Kp4z5sCVLiax)

Be sure to check all your Account Groups, as Enterprise Agents may not be assigned to all Account Groups in an organization. The Enterprise Agents page has a selector to display Agents in the current Account Group and not in the current Account Group:

![](/files/-M5xtNL2dVmMgmlNTrW6)

### Install wget and Apache Packages

Install wget and Apache’s web server (httpd). wget will be used to copy the contents of the ThousandEyes repository to your mirror.

#### For a RHEL Operating System

```
$sudo yum install wget httpd
```

#### For an Ubuntu Operating System

```
$sudo apt-get install wget httpd
```

### Configure Apache to Start Automatically

For systems using systemd to manage services run the following commands (Red Hat v7 variants, Ubuntu 16):

```
$systemctl start httpd
$systemctl is-enabled httpd
```

### Create a Directory for the Repository or Repositories

Next we’ll need a directory for the repository’s content. You’ll need at least 10 GB per repository to host this content.

#### RHEL Repository

```
$mkdir -p /var/repomirror/yum
```

#### Ubuntu Repository

```
$mkdir -p /var/repomirror/apt
```

#### Alpine Repository

```
$mkdir -p /var/repomirror/apk
```

### Set Permissions on the Directory

Change the directories of each repository to the apache user (the user is created when installing Apache):

```
$chown -R apache:apache /var/repomirror
```

### Mirror the Repository

#### RHEL Repository

```
$cd /var/repomirror/yum
$wget --mirror -e robots=off http://yum.thousandeyes.com/
$find /var/repomirror/ -type f -name '*\?C=*' -delete
$ln -s /var/repomirror/yum/yum.thousandeyes.com /var/www/html/yum
```

#### Ubuntu Repository

```
$cd /var/repomirror/apt
$wget --mirror -e robots=off http://apt.thousandeyes.com/
$find /var/repomirror/ -type f -name '*\?C=*' -delete
$ln -s /var/repomirror/apt/apt.thousandeyes.com /var/www/html/apt
```

#### Alpine Repository

```
$cd /var/repomirror/apk
$wget --mirror -e robots=off http://apk.thousandeyes.com/
$find /var/repomirror/ -type f -name '*\?C=*' -delete
$ln -s /var/repomirror/apk/apk.thousandeyes.com /var/www/html/apk
```

### Configure the Web Server

Modify the default page for Apache to be the index of the root directory by editing /etc/httpd/conf.d/welcome.conf. Change the line:

```
    Options -Indexes
```

to

```
    Options +Indexes
```

then comment out or delete the lines below the LocationMatch directive block, so that the configuration file has only:

```
<LocationMatch "^/+$">
    Options +Indexes
    ErrorDocument 403 /error/noindex.html
</LocationMatch>
```

Next, based on whether you’re going to host a Red Hat mirror, an Ubuntu mirror or both, configure Apache’s DocumentRoot (the directory that is accessed when browsing a URL path of “/”) to be the newly created repository’s parent directory. Also, set the option to allow browsing the index of that directory. The configuration file is /etc/httpd/conf/httpd.conf.

This example shows the configuration for a single mirror of the Red Hat type:

```
DocumentRoot "/var/www/html/yum"

<Directory /var/www/html/yum>
    Options Indexes FollowSymLinks
    AllowOverride None
</Directory>
```

If you are hosting an Ubuntu mirror, change the two instances of “yum” to “apt” in the above configuration. For an Alpine mirror, change to the two instances of “yum” to “apk”.

If hosting multiple types, the configuration uses the parent directory as the DocumentRoot:

```
DocumentRoot "/var/www/html"

<Directory /var/www/html/yum>
    Options Indexes FollowSymLinks
    AllowOverride None
</Directory>

<Directory /var/www/html/apt>
    Options Indexes FollowSymLinks
    AllowOverride None
</Directory>

<Directory /var/www/html/apk>
    Options Indexes FollowSymLinks
    AllowOverride None
</Directory>
```

Once edits to httpd.conf are complete, restart Apache:

```
$apachectl restart
```

### Configure SSL/TLS (optional)

If your security policies require your local mirror to run SSL/TLS, obtain and install a server certificate on the web server. This document doesn’t cover creation or installation of server certificates. Consult the Apache Project’s HTTP Server documentation and other publicly available resources.

**NOTE**: self-signed certificates cannot be used to host a repository server, as the certificate verification performed by the yum, apt, apk, and other package management utilities will fail.

### Modify iptables or Other Host-Based Firewall Rules (If Needed)

If the server is running iptables, then configure a rule (typically in the INPUT chain) to allow access to port 80/TCP from any Enterprise Agent (or port 443 if using SSL/TLS). If the server is running another type of host-based firewall, then consult the documentation for the firewall software to allow access to the web server.

### Test Your Web Server

Verify that you can access the web server in a browser on the local network. You should be able to use Chrome or another browser to load the web site on port 80/TCP and/or 443/TCP if using SSL/TLS. Ensure that you can get a directory listing of the DocumentRoot directory and the yum/apt/apk directories.

## Modify Repository Files on Your Agents

On each Enterprise Agent, you’ll need to modify the repository location in the file that the package manager consults when checking for packages. The location is based on the choice of installation type: yum, apt, or apk.

### Linux Package Using yum (RedHat Variants)

**Modify the existing repository file**

Edit /etc/yum.repos.d/thousandeyes.repo and add an enabled=0 line to the file.

#### Create a New Repository File

```
$cp /etc/yum.repos.d/thousandeyes.repo /etc/yum.repos.d/thousandeyes-mirror.repo
```

#### Edit the thousandeyes-mirror.repo File

* Change "\[thousandeyes]" to "\[thousandeyes-mirror]"
* Change "name=Thousandeyes" to "name=Thousandeyes-mirror"
* Set enabled=1
* Change "basename" to use the destination to the IP address or hostname of the web server
* Change "basename" to use the https protocol if using SSL/TLS

### Linux Package Using apt (Ubuntu variants)

#### Modify the Existing Repository File

Edit /etc/apt/sources.list.d/thousandeyes.list and comment out the one line in the top of the file by adding a # character to the beginning of the line.

#### Create a New Repository File

```
$cp /etc/apt/sources.list.d/thousandeyes.list /etc/apt/sources.list.d/thousandeyes-mirror.list
```

#### Edit the thousandeyes-mirror.list File

* Change the destination to the IP address or hostname of the web server
* Change the protocol from https to http if not using SSL/TLS

### Docker Using apk

**Modify the existing repository file**

Edit /etc/apk/repositories within the Docker container and modify the ThousandEyes repository to the IP address or hostname of the web server

Example line to modify in /etc/apk/repositories:

```
https://apk.thousandeyes.com/v3.20/thousandeyes
```

### ThousandEyes Appliance (Physical/Virtual)

Log into the ThousandEyes Virtual Appliance’s web console and select the Advanced Settings tab. For the Software Repository Location, select the "Custom option", and set the field to the correct URL for your Ubuntu-type repository, including the path to the repository if the repository is not the DocumentRoot (such as in the case of a server hosting both types of repositories). For example:

**Software Repository Location** <http://apt.mycompany.com/>

for a repository that is only hosting an apt/Ubuntu repository mirror, and

**Software Repository Location** <http://mirror.mycompany.com/apt>

for a repository that is hosting an apt/Ubuntu repository mirror and a yum/Red Hat repository mirror.

The directory you target should contain the **thousandeyes-apt-key.pub** file.

Save your changes with the **Save** button.

### Cisco Application Hosting Framework (CAF) Agents

You can edit the app-hosting configuration for supported Cisco devices to specify alternate repository URLs for the operating system and ThousandEyes repositories using these environment variables:

* `TEAGENT_REPO_URL`: The URL for an alternate Thousandeyes repository.
* `TEAGENT_OS_REPO_URL`: The URL for an alternate Alpine Linux repository.

The example configuration below configures an alternate repository for both ThousandEyes and the underlying Alpine Linux operating system:

```
Device(config)#app-hosting appid example
Device(config-app-hosting)# app-resource docker
Device(config-app-hosting-docker)# prepend-pkg-opts
Device(config-app-hosting-docker)# run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN=<token>"
Device(config-app-hosting-docker)# run-opts 2 "--hostname $(SYSTEM_NAME)"
Device(config-app-hosting-docker)# run-opts 3 "-e TEAGENT_REPO_URL=https://apkproxy.thousandeyes.com"
Device(config-app-hosting-docker)# run-opts 4 "-e TEAGENT_OS_REPO_URL=http://mirror.example.com/alpine"
Device(config-app-hosting)# end
```

Only the URL should be included in the run-opts command. The OS version and repository name will be appended automatically to the provided URL in the `/etc/apk/repositories` file. The example file below is generated from the commands above:

```
http://mirror.example.com/alpine/v3.21/main
http://mirror.example.com/alpine/v3.21/community
https://apkproxy.thousandeyes.com/v3.21/thousandeyes
```

The app-hosting container will need to be reactivated for the configuration changes to be applied to the container.

## Synchronization of the Mirror

To update the mirror’s contents, run these commands:

```
$cd /var/repomirror/yum
$wget --mirror -e robots=off http://yum.thousandeyes.com/
$cd /var/repomirror/apt
$wget --mirror -e robots=off http://apt.thousandeyes.com/
$cd /var/repomirror/apk
$wget --mirror -e robots=off http://apk.thousandeyes.com/
$find /var/repomirror/ -type f -name '*\?C=*' -delete
```

This will cause only updated versions of files to be downloaded.

**NOTE:** ThousandEyes updates Enterprise Agent software frequently. Scheduled releases occur every two weeks on Tuesdays, typically. Synchronization should be performed on a regular basis - we recommend weekly.


# Resetting an Enterprise Agent

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

Occasionally, customers may need to reset an Enterprise Agent. Resetting may be needed to repair incorrect behavior, or as the first step in reassigning the agent to a different account group.

The ThousandEyes application allows sharing of Enterprise Agents across account groups in the same organization (see the **Account Groups** setting for each agent, under the **Basic Configuration** tab of the [Agent Settings](https://docs.thousandeyes.com/product-documentation/thousandeyes-basics/working-with-agent-settings) page). However, the one account group to which an agent belongs cannot be changed through a setting in the ThousandEyes app. To change an Enterprise agent's account group, the agent must be reset and then reconfigured with the new account group's token.

This article provides instructions for resetting Enterprise Agents, according to the type of installation (such as Virtual or Physical Appliance, Linux package or Docker container). The article also provides instructions for optionally reassigning the Enterprise Agent to belong to a new account group. Prior to these instructions, the article explains where to find the account group token for an agent, and how to remove an agent from the ThousandEyes app, which is important for purposes of counting towards the number of licenses purchased. These steps are optional but may be needed depending on the reason for resetting the agent.

**Important:** Resetting an Enterprise Agent removes all configuration belonging to the existing account group, and creates a new instance of the agent in the ThousandEyes app. The new agent will not automatically assign itself to any existing tests or alerts. Test and alert assignment must be done manually after the reset. Some configuration that is local to the agent and not specific to account groups is retained.

## Account Group Token

If resetting an Enterprise Agent to change the account group, the agent will need to be configured with the new account group's installation token. The token can be found on the Enterprise Agent Settings page under **Network & App Synthetics > Agent Settings > Enterprise Agents**. Select the **+ Add New Enterprise Agent** form. The Account Group Token field appears under the **Appliance** view. Reveal the token by clicking the "eye" icon within the field.

![](/files/-M62_Wl77l5gRQFUE8_O)

Select and copy the account group token for later use.

The Linux Package and Docker settings will also display the token, in the text of their installation instructions.

Access to the account group token requires a user account with a role that has the *View agents in account group* and *Edit agents in account group* permissions.

## Removing Old Agent Entries

Resetting an Enterprise Agent will assign the agent a new, unique ID number in the ThousandEyes application, and will create a new entry in the [Enterprise Agent Settings](https://app.thousandeyes.com/network-app-synthetics/agent-settings/enterprise/?section=agents) page, in the agent's account group.

To avoid using an additional Enterprise Agent license, as well as avoiding confusion and accumulating out-of-date information, the entry for the agent should be removed from the Enterprise Agent Settings page before resetting an Enterprise Agent, unless a specific reason to keep the entry exists. Resetting an agent without deleting the old agent's entry in the ThousandEyes app could result in an extra license used in the billing cycle, as the ThousandEyes app does not know that the agent has been reset; only that the old agent hasn't reported to ThousandEyes and a new agent has been created.

On the Enterprise Agent Settings page, expand the entry for the agent and click the Delete dropdown option.

![](/files/-M5xtQ0i6HEMLtHsoYvH)

If the old entry is not removed before the agent is reset, and the agent is not being reassigned to a new account group, then the new agent will be created with a name which has the new agent's unique numerical ID appended to the name, in order to have a unique name. For example, resetting the agent called "superteva" without first deleting the entry in the Settings page will result in the new agent having a name "superteva-XXXXX" where XXXXX is the new agent ID.

If the entry is not deleted prior to reset, and the new agent name appears with the appended ID, the old agent entry can be deleted, and then the new agent name edited to return to the old name, if desired. Simply edit the **Agent Name** field and click the **Save Changes** button. Note however that using the existing name will not preserve test or alert configuration that the reset deletes.

## Resetting an Appliance

Resetting a Virtual or Physical Appliance is done using the web console of the Appliance. Access to the Appliance's web console is done using the IP address of the Appliance. The IP address can be found by accessing the [Enterprise Agent Settings](https://app.thousandeyes.com/network-app-synthetics/agent-settings/enterprise/?section=agents) page, or by opening a console connection to the Appliance. In the console, the IP address and login credentials will be shown as per the example below:

![](/files/-M5xtQ0jWlrFEAGKYqnK)

1. Browse to [https://\<Appliance\_IP\_address>](/product-documentation/global-vantage-points/enterprise-agents/managing/resetting-an-enterprise-agent) then log in to the web console
2. Open the **Advanced Settings** tab

   ![](/files/-M5xtQ0kSFCF9Spfy4jP)
3. Click the **Reset Agent State** button
4. Confirm the reset operation

The user will be logged out of the Appliance. Log back in using the same credentials. The agent will display the Setup wizard:

![](/files/-M5xtQ0lUE6WVlKYdwNt)

The agent may now be set up using the instructions for configuring a new Appliance. If configuring the agent for a new account group, provide the new account group's installation token during step 4, and make any other changes on the Appliance if needed. Once the Setup wizard has completed, navigate to the Status tab to ensure that the agent is running, and return to the [Enterprise Agent Settings](https://app.thousandeyes.com/network-app-synthetics/agent-settings/enterprise/?section=agents) page for the appropriate account group to confirm that the agent is present.

### Troubleshooting

If the Appliance does not appear on the Enterprise Agent Settings page after reset, check the following:

* Run diagnostics from the web console's Diagnostic tab
* Log into app.thousandeyes.com with a username which can access the agent's current account group, view the installation token (see instructions above) and compare to the installation token on the web console's Agent tab
* Check the **Show agents not assigned to this account group** box on the [Enterprise Agent Settings](https://app.thousandeyes.com/network-app-synthetics/agent-settings/enterprise/?section=agents) page and search for the agent in the listing
* Check the Agent Log under the web console's Diagnostic tab (or log into the agent's command line using SSH and view /var/log/te-agent.log) for indications of an agent ID change. An agent will normally show a log line at startup like:

```
  2018-05-01 20:42:26.300 INFO  [537197c0] [te.agent.main] {} Found id 56567
```

If the agent has been reset and has obtained a new ID, the log will show a line at startup like:

```
  2018-05-16 22:20:45.231 INFO  [d349e7c0] [te.agent.main] {} No agent id found, attempting to obtain one from sc1.thousandeyes.com
```

## Resetting a Linux Package Agent

To reset an Enterprise Agent that has been installed on a [supported Linux operating system](https://docs.thousandeyes.com/product-documentation/enterprise-agents/supported-enterprise-agent-operating-systems) with the Linux package, log into the command line of the Linux system running the Agent, using an account which has sudo privileges. Issue the following commands:

1. Stop the agent process by running:

   ```
   sudo systemctl stop te-agent
   ```
2. Delete the .sqlite files located in the /var/lib/te-agent/ directory:

   ```
   sudo rm /var/lib/te-agent/*.sqlite
   ```
3. Optionally, if you wish to change the account group of the agent, edit the configuration file /etc/te-agent.cfg and change the value of the **account-token** setting to use the new account group token.
4. Restart the agent process:

   ```
   sudo systemctl start te-agent
   ```

### Troubleshooting

If the Linux package-based agent does not appear on the Enterprise Agent Settings page after reset, check the following:

* Log into app.thousandeyes.com with a username which can access the agent's current account group, view the installation token (see instructions above) and compare to the installation token in the /etc/te-agent.cfg file
* Check the **Show agents not assigned to this account group** box on the [Enterprise Agent Settings](https://app.thousandeyes.com/network-app-synthetics/agent-settings/enterprise/?section=agents) page and search for the agent in the listing
* Check the agent logs /var/log/te-agent.log for indications of an agent ID change. An agent will normally show a log line at startup like:

```
  2018-05-01 20:42:26.300 INFO  [537197c0] [te.agent.main] {} Found id 56567
```

If the agent has been reset and has obtained a new ID, the log will show a line at startup like:

```
  2018-05-16 22:20:45.231 INFO  [d349e7c0] [te.agent.main] {} No agent id found, attempting to obtain one from sc1.thousandeyes.com
```

## Resetting a Docker Container Agent

To reset an Enterprise Agent that has been installed via a Docker container, log into the command line of the system running Docker (Docker host), using an account which has sudo privileges. Issue the following commands:

1. Stop the container:

   ```
   sudo docker stop <container_name>
   ```
2. Delete the persistent storage directory which was created with the -v option of the docker run command:

   ```
   sudo rm -rf <persistent_volume_directory>/thousandeyes/<container_name>
   ```

   **Note:** If you wish to retain any files in the directories for the Docker agent, such as agent or BrowserBot logs, copy them to another location before running the rm command.
3. Optionally, if you wish to change the account group of the agent, re-run the docker run command which was used to create the container, and use the new account group token when specifying the following option:

   ```
   -e TEAGENT_ACCOUNT_TOKEN=<new_Account_Group_token>
   ```
4. If not performing step 3, then restart the container:

   ```
   sudo docker start <container_name>
   ```

### Troubleshooting

If the Docker container-based agent does not appear on the Enterprise Agent Settings page after reset, check the following:

* Log into app.thousandeyes.com with a username which can access the agent's current account group, view the installation token (see instructions above) and compare to the installation token used in the TEAGENT\_ACCOUNT\_TOKEN option
* Check the **Show agents not assigned to this account group** box on the [Enterprise Agent Settings](https://app.thousandeyes.com/network-app-synthetics/agent-settings/enterprise/?section=agents) page and search for the agent in the listing
* Check the agent logs in \<persistent\_volumen\_directory>/thousandeyes/\<container\_name>/log on the Docker host for indications of an agent ID change. An agent will normally show a log line at startup like:

```
  2018-05-01 20:42:26.300 INFO  [537197c0] [te.agent.main] {} Found id 56567
```

If the agent has been reset and has obtained a new ID, the log will show a line at startup like:

```
  2018-05-16 22:20:45.231 INFO  [d349e7c0] [te.agent.main] {} No agent id found, attempting to obtain one from sc1.thousandeyes.com
```

## Resetting a Cisco Docker Agent

{% hint style="info" %}
These steps are a variant on "Reconfiguring the Docker Container".
{% endhint %}

### Part 1: Update the Cisco app-hosting app to the new token

1. Stop the application:

   ```
   app-hosting stop appid thousandeyes_enterprise_agent
   ```
2. De-activate the application:

   ```
   app-hosting deactivate appid thousandeyes_enterprise_agent
   ```
3. Modify the Docker options, and exit three times:

   ```
   app-hosting appid thousandeyes_enterprise_agent
   catalyst(config-app-hosting)#app-resource docker
   catalyst(config-app-hosting-docker)#prepend-pkg-opts
   catalyst(config-app-hosting-docker)#run-opts 1 "-e TEAGENT_ACCOUNT_TOKEN=<Token>"
   catalyst(config-app-hosting-docker)#exit
   catalyst(config-app-hosting)#exit
   catalyst(config)#exit
   ```
4. Reactivate the application, and confirm that it’s activated:

   ```
   app-hosting activate appid thousandeyes_enterprise_agent
   ```
5. Start the application, and confirm that it is running:

   ```
   app-hosting start appid thousandeyes_enterprise_agent
   ```

### Part 2: getting the agent to use the new token

1. Connect to the agent's shell

   ```
   app-hosting connect appid thousandeyes_enterprise_agent session
   ```
2. Stop the agent:

   ```
   sv stop te-agent
   ```
3. Remove the old agent configuration files.

   **For Cisco Switches:**

   ```
   rm -rfv /iox_data/appdata/te-agent-config.sqlite
   rm -rfv /var/lib/te-agent/data/te-agent.sqlite
   ```

   **For Cisco Routers:**

   ```
   rm -rfv /data/appdata/te-agent-config.sqlite
   rm -rfv /var/lib/te-agent/data/te-agent.sqlite
   ```
4. Start the agent:

   ```
   sv start te-agent
   ```


# Working with Enterprise Agent Clusters

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

In environments where there are more than one enterprise agent running in a single location, administrators may want to simplify the agent selection process for their end users, by abstracting the number of Enterprise Agents running from a single location into an agent cluster. Additionally, clustering provides the benefit of assigning new tests to the least utilized member of a cluster, for the given test type.

ThousandEyes Cloud Agents operate using the same concept as Enterprise Agent clusters: there are multiple independent servers operating together to run tests from a single location.

## Prerequisites

To manage Enterprise Agent clusters, your role must include the following permissions:

* *Edit agent notifications*
* *Edit agents in account group*

For more information, see [Role-Based Access, Explained](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control/role-based-access-control-explained).

## Creating a Cluster

To create a cluster, click the **Add to Cluster** link shown at the bottom of an Enterprise Agent's Settings. A dialog will open; choose to either add to a new cluster, or add to an existing cluster, and give the cluster a name. By default, the cluster will inherit the name of the first cluster member.

![](/files/-M5xtFHWwDl8Nty8qyJv)

When the new cluster is created, all agent settings will be automatically mapped to the new cluster. This includes:

* Inherit all tests assigned to the standalone agent
* All accounts which had access to the standalone agent
* Agent groups where the standalone agent was a member
* Agent settings:
  * Verify SSL certificates setting
  * Agent notification rules selections
* For customers using the API, the cluster retains the agentId of the first agent added to the cluster

## Adding Capacity to a Cluster

Once a cluster is created, more agents can be added to the cluster, by running through the same process and clicking the add to existing cluster, then selecting the cluster.

![](/files/g6sP8JI4ruOaxHMLnbAX)

When adding a new agent to an existing cluster, the cluster will:

* Inherit all tests assigned to the agent
* Ignore all groups assigned to the newly assigned agent
* Enforce the cluster settings for:
  * Verify SSL certificates setting
* For customers using the API, the newly assigned agent's agentID will no longer exist

If a test on an inbound agent is already assigned to the cluster, one agent will appear as removed from the test.

## Deleting a Cluster

To delete an Enterprise Agent cluster, navigate to **Network & App Synthetics > Agent Settings > Clusters**. Expand the Enterprise Agent cluster's row, then click the trash icon in the lower left corner. Note that deleting a cluster with existing Enterprise Agent cluster members will also delete the Enterprise Agents. To preserve the Enterprise Agents, remove them from the cluster before deleting the cluster. See the section below for instructions on removing an agent from a cluster.

## Removing an Agent from a Cluster

In certain cases, an Administrator may want to remove an agent from a cluster. To accomplish this, under the Settings menu, select Enterprise Agents, and choose the Cluster tab. Expand the Enterprise Agent cluster's row, then click the **x** icon next to the cluster member. You'll be shown a confirmation dialog:

{% hint style="warning" %}
You can't remove the last remaining Enterprise Agent from a cluster. Instead, select **Convert to Enterprise Agent** to convert the cluster to a standalone Enterprise Agent. This action is equivalent to removing the final cluster member.
{% endhint %}

![](/files/RPAusNwG7auxoLUeWWlN)

Click the **Remove** button to remove the agent from the cluster and return the agent to a standalone status. This operation removes the agent, and recreates it in the context of the user's current account group, so be aware of your current account group, in the event that your user has management permissions across multiple account groups. The agent is created fresh, inheriting default Agent Notification rules, and without any tests assigned.

## Agent Management

In the Enterprise Agents page, you'll be able to tell which agent is a cluster member by looking at the expanded agent details of an agent, or the cluster icon. Click the cluster hyperlink to open the cluster settings, and view other cluster members.

![](/files/09zZrpxssM8AIc7en26c)

Utilization details for the agent are shown at the cluster member level, as well as on an overall basis at the cluster level.

It's important to note that Enterprise Agent clusters are not meant for high availability of agents. If a cluster member is shut down or becomes unreachable via the network while tests are assigned to it, those tests will remain assigned to that same agent (cluster member). Removing the agent from a cluster will force redistribution of those tests to other cluster members.

## Test Management and Utilization

New tests assigned to the cluster are distributed to each cluster member, based on each agent's utilization. As a new agent is assigned, the tests assigned to that agent are distributed amongst the cluster members.

If a member agent in a cluster is deleted or overloaded, the tests assigned to that agent are redistributed among the remaining cluster members. Auto-rebalancing can only be triggered when there are agent members with available capacity.

Utilization is shown for each agent in the agent settings page, and the overall cluster utilization shows the average value across all cluster members.

## Views and Results

Views will show the name of the agent as the cluster name, but show the individual IP address of the cluster member. This may include private and/or public IP information, so to troubleshoot individual cluster members having problems resolving data on a test, you'll have to identify the cluster member assigned to the test, and diagnose from that specific agent. To view the information for a specific test, hover over the agent icon.

![](/files/8AXpgeHekEaT9YmffOXJ)

## Agent-to-Agent Tests

Using a cluster as a target for agent-to-agent tests will work fine, unless all agents are behind the same NAT. In this scenario, you'll need to create a firewall rule for the target, which would point to a specific agent in the cluster. While all results will behave as planned, the agent targeted will absorb all agent-to-agent tests targeted at that specific port on the cluster. To target different agents, change the port of the target, which is set under the Advanced Settings tab of the test's configuration.

## API Support

ThousandEyes API versions 5 and later support Enterprise Agent clusters. For more information, see the [ThousandEyes API documentation](https://developer.cisco.com/docs/thousandeyes/v7/), where you can find details about Enterprise Agent clusters.

## Restrictions

* All agents must be owned by the same account group (i.e. use the same account token)
* All agents must be using the same address family (no mixing of IPv4 agents with IPv6 agents)

## Recommendations

* Agents should be running the same version of both operating system and agent software
* Agents should have similar hardware configuration
* Agents should be in the same physical location
* Agents should be running the same components (ie, all agents run both agent and BrowserBot, or just agent)


# Replacing an Enterprise Agent Using the Agent Clustering Method

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

For a variety of reasons, you may need to replace an Enterprise Agent that is currently operational. When replacement is required, you may want to preserve the agent's configuration (such as the agent's name, or settings from the **Advanced Settings** tab of the agent's entry on the [**Enterprise Agent** page](https://app.thousandeyes.com/network-app-synthetics/agent-settings/enterprise/)) and the tests and account groups to which the Enterprise Agent has been assigned. The information below provides a process to quickly substitute the new Enterprise Agent for the old, using the ThousandEyes Enterprise Agent cluster feature.

The process below not only makes replacement faster and simpler than manual reconfiguration of an agent, but ensures that organizations that have limits or that are billed for overages to their contracted number of concurrently active Enterprise Agents do not encounter problems due to those limits.

For more information and alternative upgrading methods, see [How to Plan for Enterprise Agent Upgrades](https://docs.thousandeyes.com/product-documentation/enterprise-agents/how-to-plan-for-enterprise-agent-upgrades).

## Overview

The replacement process consists principally of the following steps:

1. Create a new cluster using the agent that needs to be replaced.
2. Disable the new cluster.
3. Create the new agent.
4. Add the new agent to the cluster.
5. Delete the old agent.
6. Enable the new cluster or remove the cluster and enable the agent.

For more detailed instructions, see the section below.

## Detailed Instructions

1. Create a new cluster using the agent that needs to be replaced.

   Go to the **Network & App Synthetics > Agent Settings > Enterprise Agents** page, expand the row of the agent requiring replacement, and click **Add agent to cluster**.\
   More information about clusters can be found in [Working with Enterprise Agent Clusters](https://docs.thousandeyes.com/product-documentation/enterprise-agents/working-with-enterprise-agent-clusters).

   ![](/files/-M62_Wm8pe2NEF_l9W0Z)

   Name the new cluster.

   ![](/files/-M62_WmEeLhUhdMeHLmP)
2. Disable the new cluster.

   Disabling the cluster will prevent overages for additional agents or errors for exceeding your contracted number of concurrent agents.

   ![](/files/-M62_WmK0S-dRSMStbty)
3. Create the new agent.

   Links to the most common deployment options are below.

   * [Re-Initializing an Enterprise Agent](https://docs.thousandeyes.com/product-documentation/enterprise-agents/resetting-an-enterprise-agent) (This will wipe an existing agent's settings and cause it to appear as a new agent)
   * [ThousandEyes Virtual Appliance Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-virtual-appliance-installation)
   * [Linux Package Agent Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/linux-package-agent-installation)
   * [Enterprise Agent Deployment Using Docker](https://docs.thousandeyes.com/product-documentation/enterprise-agents/enterprise-agent-deployment-using-docker)
4. Add the new agent to the cluster.

   Expand the row belonging to the new agent, and click **Add agent to cluster**.

   ![](/files/-M62_WmQz32HIuap5FZl)

   When the **Add Agent to Cluster** window appears, click **Add to existing cluster**, then select the name of the cluster in the drop-down box.

   ![](/files/-M62_WmWIWnMBBIP37iC)
5. Delete the old agent.

   ![](/files/-M62_WmaS1hzLcxDzTKj)

   Confirm deletion.

   ![](/files/-M62_WmgathPUA9gka4r)
6. Enable the new cluster (1) or convert the cluster back into an agent (2)

   ![](/files/-M62_WmmjNEhUbgbiixR)

## Related Information

Consult [How to Plan for Enterprise Agent Upgrades](https://docs.thousandeyes.com/product-documentation/enterprise-agents/how-to-plan-for-enterprise-agent-upgrades) for more information regarding Enterprise Agent upgrades and available upgrade methods.

If you have questions, [contact the ThousandEyes Customer Engineering team](https://docs.thousandeyes.com/product-documentation/getting-started/getting-support-from-thousandeyes).


# Replacing an Enterprise Agent Using Agent Identity Files

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

## Replacement Overview

ThousandEyes Enterprise Agents can be replaced by using one of the following methods:

1. **Agent Clustering Method:**

   This method consists of deploying a new agent, clustering together the new agent with the old one, and then deleting the old agent from the cluster. The act of clustering transfers test associations and agent characteristics. Detailed instructions for this method are available in [Replacing an Enterprise Agent Using the Agent Clustering Method](https://docs.thousandeyes.com/product-documentation/enterprise-agents/replacing-an-enterprise-agent-using-the-agent-clustering-method))
2. **Transferring Agent Identity Files:**

   During the installation of a replacement Enterprise Agent, identity files from an existing Enterprise Agent are transferred to the replacement system. The platform will make no distinction between the original agent and the replacement agent.

This document will demonstrate how to successfully transfer Enterprise Agent identity files from an existing to a newly deployed agent.

## Enterprise Agent Identity Files

The Enterprise Agent software package is installed as a service named `te-agent` onto a [supported Linux operating system](https://docs.thousandeyes.com/product-documentation/enterprise-agents/supported-enterprise-agent-operating-systems). The following three files are used by the `te-agent` service during operation and must be transferred from the original agent to the replacement agent:

#### /etc/te-agent.cfg

* This is the agent's main configuration file and contains account group information, logging, and proxy settings
* During service start, `te-agent` reads this file and applies configuration settings
* This file is not unique to a specific agent and may be re-used to configure identical settings to multiple agents

#### /var/lib/te-agent/te-agent-config.sqlite

* This file contains the agent ID, collector assignment, and current runtime configuration settings
* Information within this file is used to authenticate with the ThousandEyes platform
* **WARNING: This file is unique to the agent and must not be used by two agents at the same time. DO NOT copy this file to more than one replacement Agent.**

#### /var/lib/te-agent/te-agent.sqlite

* This file contains the not-yet-submitted test and device layer data
* **WARNING: This file is unique to the agent and must not be used by two agents at the same time. DO NOT copy this file to more than one replacement Agent.**

## Obtaining Identity Files from the Original Agent

### Disable the Original Enterprise Agent Using the ThousandEyes Web Application

Prior to obtaining Enterprise Agent identity files, it is recommended to temporarily disable the Enterprise Agent to be replaced:

Select **Network & App Synthetics > Agent Settings** within the left-hand navigation pane

**1.** Review the list of active Enterprise Agents for the name of the agent to be replaced\
**2.** Click the **options** button in the right-hand side of the agent information row and select **Disable**

### Stop and Disable the Original Enterprise Agent Service

ThousandEyes service must be stopped on your original agent before you may copy identity files. Disabling the service will prevent the decommissioned agent from communicating with the ThousandEyes platform in the event that the VM is restarted.

**Operating systems using systemd (Ubuntu 16.04+, RHEL & CentOS 7+):**

```
$ sudo sytemctl stop te-agent.service
$ sudo systemctl disable te-agent.service
```

**RHEL 6 & CentOS 6:**

```
$ sudo service te-agent stop
$ sudo chkconfig te-agent off
```

**Ubuntu 14.04:**

```
$ sudo stop te-agent
$ sudo update-rc.d -f te-agent remove
```

### Copy Enterprise Agent Identity Files to a Single Directory

Copy identity files to a single directory for ease of management:

```
$ cd ~
$ sudo mkdir <directory_name>
$ sudo cp /var/lib/te-agent/*.sqlite ~/<directory_name>
$ sudo cp /etc/te-agent.cfg ~/<directory_name>
```

### Compress the Directory Containing Your Original Agent Identity Files

Compress the directory containing copied identity files for ease of transfer

```
$ sudo zip -r <directory_name>.zip <directory_name>
```

### Delete the Agent Identity Files From Your Original Agent

While the original Identity files will be deleted when the VM is destroyed, it is always possible that the VM could be restarted prior to deletion. Removing these files safeguards from errors associated with two agents connecting to the platform with the same agent ID.

```
original-agent$ sudo rm /etc/te-agent.cfg
original-agent$ sudo rm /var/lib/te-agent/*.sqlite
```

## Transferring Identity Files

### Use SCP to Transfer Files Between Agents

From your new replacement agent's terminal, you may use the following command to obtain files from your original agent (provided the original and the new Enterprise Agent can communicate with each other directly):

```
$ scp <user>@<original-agent-IP>:~/<directory_name>.zip ~
```

Alternatively, from your original agent's terminal you may use the following command to transfer files to your replacement agent:

```
$ scp ~/<directory_name>.zip <user>@<replacement-agent-IP>:~
```

**NOTE:** You only need to copy the .zip file once.

## Installing a Replacement Agent Using Transferred Identity Files

### Install the ThousandEyes Repository

You will use the ThousandEyes repository to download and install Enterprise Agent services:

**Ubuntu:**

```
$ sudo apt-get update
$ sudo apt-get install software-properties-common
$ sudo apt-add-repository https://apt.thousandeyes.com/
```

**RHEL 7:**

```
$ sudo yum-config-manager --add-repo https://yum.thousandeyes.com/RHEL/7/x86_64
```

**CentOS 7:**

```
$ sudo yum-config-manager --add-repo https://yum.thousandeyes.com/CentOS/7/x86_64
```

### Install the ThousandEyes Repository GPG Key

You must install the ThousandEyes repository GPG key in order to validate the authenticity of downloaded packages:

**Ubuntu:**

```
$ sudo wget -q https://apt.thousandeyes.com/thousandeyes-apt-key.pub
$ sudo apt-key add thousandeyes-apt-key.pub
```

**RHEL & CentOS 7:**

```
$ sudo  rpm --import https://yum.thousandeyes.com/RPM-GPG-KEY-thousandeyes
```

### Update Your Operating System's Package Manager

Pulling the repository metadata verifies that the ThousandEyes repository and corresponding GPG key are properly installed:

**Ubuntu:**

```
$ sudo apt-get update
```

**RHEL & CentOS 7:**

```
$ sudo yum clean metadata
$ sudo yum updateinfo
```

### Install the ThousandEyes Enterprise Agent Using Your OS's Package Manager

The `te-agent` package and service are what constitutes the heart of an Enterprise Agent. The [BrowserBot](https://docs.thousandeyes.com/product-documentation/enterprise-agents/what-is-browserbot) component (the `te-browserbot` package and service) is a component that performs browser-based tests.

**Ubuntu:**

```
$ sudo apt-get install te-agent te-browserbot
```

**RHEL & CentOS 7:**

```
$ sudo yum install te-agent te-browserbot
```

### Decompress the Original Agent Identity Files Within Your Replacement System

Once decompressed, a directory with the same name as the directory from your original agent will be available:

```
$ unzip <directory_name>.zip
```

### Copy the Agent Identity Files to the Target Directories Within Your Replacement System

Copy the agent identity files to their final location:

```
$ sudo cp <directory_name>/*.sqlite /var/lib/te-agent
$ sudo cp <directory_name>/te-agent.cfg /etc
```

### Start and Enable Enterprise Agent Services

Starting agent services will activate the ThousandEyes agent. Enabling a service ensures that it will start during system boot. To start and enable relevant services, execute the following commands:

```
$ sudo systemctl start te-agent.service
$ sudo systemctl start te-browserbot.service
$ sudo systemctl enable te-agent.service
$ sudo systemctl enable te-browserbot.service
```

## Verifying Replacement

Once your replacement agent has been brought online, you may re-enable your agent within the ThousandEyes web application:

Select **Network & App Synthetics > Agent Settings** within the left-hand navigation pane and:

**1.** Review the list of active Enterprise Agents for the name of the agent that was replaced.\
**2.** Click the options button in the right-hand side of the agent information row and select **Enable**.

Upon completion, review the **Advanced Settings** section to ensure that the agent information is correct:

Select the **Advanced Settings** tab of your Enterprise Agent information pane:

**1.** Verify that your Enterprise Agent is checking into the platform regularly\
**2.** Verify that the IP address and listed Operating System are correct\
**3.** Review the proxy settings (if applicable) to verify that they are correct

## Troubleshooting

If you have any questions regarding the described agent replacement procedure or if you hit an obstacle while performing it, [reach out to the ThousandEyes Customer Engineering team](https://docs.thousandeyes.com/product-documentation/getting-started/getting-support-from-thousandeyes) and we'll help you out.


# Unlocking the ThousandEyes Appliance

The ThousandEyes Virtual Appliance (VA) and Physical Appliance (PA) provide a limited number of administrative commands via the `sudo` utility, when users access the command line using SSH as user thousandeyes. If greater control over the operating system and the ThousandEyes Agent software is required, the VA can be “unlocked”, which gives the thousandeyes user the ability to use any command via `sudo`.

**NOTE:** Changes which require unlocking the Virtual Appliance will not be supported by ThousandEyes. A Virtual Appliance which becomes inaccessible, unstable, or otherwise unusable after such changes will require reinstallation of the Virtual Appliance.

Support for unlocked virtual appliances is reduced to the same support offered for Linux package install. This means that we will no longer support operating system related issues, as we are unable to verify what changes may have been made, nor can we verify the impact that any changes can have on the agent.

## Unlocking an Appliance

To unlock the Appliance, install the **te-va-unlock** package from the ThousandEyes APT repository (apt.thousandeyes.com). Installing the package is done from the command line of the Appliance. Access the command line via SSH. See the following articles to configure SSH access from your operating system:

[Connecting to the ThousandEyes Virtual Appliance using SSH (Mac/Linux)](https://docs.thousandeyes.com/product-documentation/enterprise-agents/connecting-to-the-thousandeyes-virtual-appliance-using-ssh-mac-linux)\
[Connecting to the ThousandEyes Virtual Appliance using SSH (Windows)](https://docs.thousandeyes.com/product-documentation/enterprise-agents/connecting-to-the-thousandeyes-virtual-appliance-using-ssh-windows)

Once you have accessed the Appliance via SSH, issue the following commands to install the package:

```
sudo apt-get update
sudo apt-get install te-va-unlock
```

The `te-va` process will be restarted at the conclusion of the installation.

An example of unlocking an Appliance is show below:

```
thousandeyes@binky-thousandeyes-va:~$ sudo apt-get install te-va-unlock

Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following NEW packages will be installed:

  te-va-unlock

0 upgraded, 1 newly installed, 0 to remove and 10 not upgraded.
Need to get 848 B of archives.
After this operation, 0 B of additional disk space will be used.
Get:1 http://apt.thousandeyes.com/ trusty/main te-va-unlock amd64 0.96-1~trusty [848 B]
Fetched 848 B in 0s (3405 B/s)  
Selecting previously unselected package te-va-unlock.
(Reading database ... 37645 files and directories currently installed.)
Preparing to unpack .../te-va-unlock_0.96-1~trusty_amd64.deb ...
Unpacking te-va-unlock (0.96-1~trusty) ...
Setting up te-va-unlock (0.96-1~trusty) ...
te-va stop/waiting
te-va start/running, process 2599
```

An unlocked Appliance's web interface will display a red "Unlocked" icon, as shown in the image below. If the unlock process was run after logging into the Appliance's web interface, then log out and log back into the web interface to see the Unlocked icon.

![](/files/-M5xtNIp5A5UPyxypCdn)

## ThousandEyes Virtual Appliance Sudo Password

The "thousandeyes" user account exists on the appliance to allow you to do limited troubleshooting. The appliance may be accessed via SSH after [setting up SSH keys](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/connecting-to-the-thousandeyes-virtual-appliance-using-ssh-mac-linux) for the "thousandeyes" user via the agent portal.

If more advanced troubleshooting is needed, ThousandEyes Support can, in conjunction with the customer, gain sudo access to the appliance using the "thousandeyes" user account password. This password cannot be used for remote access to the appliance.


# Uninstalling the Enterprise Agent (Linux Package)

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

Customers may need to remove the Enterprise Agent software which was installed on a supported Linux operating system from the **te-agent** and (optionally) **te-browserbot** packages. Additionally, customers may optionally remove the configuration files created by the agent. Customers may wish to keep the agent configuration files if the reason for removal is to fix a broken agent. Reinstalling agent software with existing configuration files allows the agent to resume running with the configuration of tests and other settings present prior to removing the agent software.

This article describes the steps required to remove an Enterprise Agent from each of the supported Linux distributions.

## Ubuntu

1. Check if the **te-agent** and the **te-browserbot** services are running:

   ```
   $ sudo systemctl status te-agent
   ● te-agent.service - ThousandEyes Agent
      Loaded: loaded (/lib/systemd/system/te-agent.service; enabled; vendor preset:
      Active: active (running) since Tue 2017-04-04 12:11:49 CDT; 2min 5s ago
    Main PID: 1052 (te-agent)
       Tasks: 24
      Memory: 29.0M
         CPU: 1.182s
      CGroup: /system.slice/te-agent.service
              └─1052 /usr/local/bin/te-agent -C /etc/te-agent.cfg
   $ sudo service te-browserbot status
   ● te-browserbot.service - ThousandEyes BrowserBot
      Loaded: loaded (/lib/systemd/system/te-browserbot.service; enabled; vendor pr
      Active: active (running) since Tue 2017-04-04 12:12:16 CDT; 2min 17s ago
    Main PID: 1596 (java)
       Tasks: 90
      Memory: 162.0M
         CPU: 14.426s
      CGroup: /system.slice/te-browserbot.service
   ```
2. Stop the **te-agent** and the **te-browserbot** services:

   ```
   $ sudo systemctl stop te-agent
   $ sudo systemctl status te-agent
   ● te-agent.service - ThousandEyes Agent
      Loaded: loaded (/lib/systemd/system/te-agent.service; enabled; vendor preset:
      Active: inactive (dead) since Tue 2017-04-04 12:16:29 CDT; 9s ago
     Process: 3632 ExecStart=/usr/local/bin/te-agent -C /etc/te-agent.cfg (code=kil
    Main PID: 3632 (code=killed, signal=TERM)

   $ sudo systemctl stop te-browserbot
   $ sudo systemctl status te-browserbot
   ● te-browserbot.service - ThousandEyes BrowserBot
      Loaded: loaded (/lib/systemd/system/te-browserbot.service; enabled; vendor pr
      Active: inactive (dead) since Tue 2017-04-04 12:17:03 CDT; 8s ago
     Process: 3696 ExecStart=/usr/bin/java -Djava.io.tmpdir=/var/lib/te-browserbot/
    Main PID: 3696 (code=exited, status=143)
   ```
3. Purge the **te-agent** and the **te-browserbot** packages: If you're planning to re-install the agent software use "apt-get remove" instead of "apt-get purge". This will leave the necessary configuration files intact, so that once the agent is re-installed, there is no need to re-assign tests to it.

   ```
   $ sudo apt-get purge te-agent
   Removing te-agent (1.9.1-1~xenial) ...
   Updating certificates in /etc/ssl/certs...
   0 added, 0 removed; done.
   Running hooks in /etc/ca-certificates/update.d...

   done.
   done.
   Purging configuration files for te-agent (1.9.1-1~xenial) ...
   Updating certificates in /etc/ssl/certs...
   0 added, 0 removed; done.
   Running hooks in /etc/ca-certificates/update.d...

   done.
   done.


   $ sudo apt-get purge te-browserbot
   (Reading database ... 68880 files and directories currently installed.)
   Removing te-browserbot (1.38-1~xenial) ...
   Removing user `browserbot' ...
   Warning: group `browserbot' has no more members.
   Done.
   ```
4. Verify that both packages have been removed:

   ```
   $ sudo systemctl status te-agent
   ● te-agent.service
      Loaded: not-found (Reason: No such file or directory)
      Active: inactive (dead) since Tue 2017-04-04 12:16:29 CDT; 7min ago
    Main PID: 3632 (code=killed, signal=TERM)

   $ sudo systemctl status te-browserbot
   ● te-browserbot.service
   Loaded: not-found (Reason: No such file or directory)
   Active: inactive (dead) since Tue 2017-04-04 12:17:03 CDT; 7min ago
    Main PID: 3696 (code=exited, status=143)
   ```

## RHEL/CentOS/Oracle Linux 6.x

1. Check if the **te-agent** and the **te-browserbot** services are running:

   ```
   $ status te-agent
   te-agent start/running, process 17228

   $ status te-browserbot
   te-browserbot start/running, process 17214
   ```
2. Stop the **te-agent** and the **te-browserbot** services:

   ```
   $ sudo stop te-agent
   te-agent stop/waiting

   $ sudo stop te-browserbot
   te-browserbot stop/waiting
   ```
3. Remove the **te-agent** and the **te-browserbot** services:

   For those who wish to remove dependencies, use *yum erase* instead of *yum remove:*

   ```
   $ sudo yum remove te-agent

   $ sudo yum remove te-browserbot
   ```
4. Verify that the **te-agent** and the **te-browserbot** services have been removed:

   ```
   $ status te-agent
   status: Unknown job: te-agent

   $ status te-browserbot
   status: Unknown job: te-browserbot
   ```

## RHEL/CentOS/Oracle Linux 7.x

1. Check if the **te-agent** and the t**e-browserbot** services are running:

   ```
   $ sudo systemctl status te-agent
   ● te-agent.service - ThousandEyes Agent
      Loaded: loaded (/usr/lib/systemd/system/te-agent.service; enabled; vendor preset: disabled)
      Active: active (running) since Thu 2017-03-30 11:31:35 EDT; 7s ago

   $ sudo systemctl status te-browserbot
   ● te-browserbot.service - ThousandEyes BrowserBot
      Loaded: loaded (/usr/lib/systemd/system/te-browserbot.service; enabled; vendor preset: disabled)
      Active: active (running) since Thu 2017-03-30 11:31:41 EDT; 5s ago
   ```
2. Stop the **te-agent** and the **te-browserbot** services:

   ```
   $ sudo systemctl stop te-agent
   $ sudo systemctl status te-agent
   ● te-agent.service - ThousandEyes Agent
      Loaded: loaded (/usr/lib/systemd/system/te-agent.service; enabled; vendor preset: disabled)
      Active: inactive (dead) since Thu 2017-03-30 11:25:12 EDT; 4min 46s ago

   $ sudo systemctl stop te-browserbot
   $ sudo systemctl status te-browserbot
   ● te-browserbot.service - ThousandEyes BrowserBot
      Loaded: loaded (/usr/lib/systemd/system/te-browserbot.service; enabled; vendor preset: disabled)
      Active: inactive (dead) since Thu 2017-03-30 11:28:25 EDT; 1min 40s ago
   ```
3. Remove the **te-agent** and the **te-browserbot** services:

   For those who wish to remove dependencies, use *yum erase* instead of *yum remove.*

   ```
   $ sudo yum remove te-agent
   Removed:
     te-agent.x86_64 0:1.9.0-1

   $ sudo yum remove te-browserbot
   Removed:
     te-browserbot.x86_64 0:1.38-1
   ```
4. Verify that the **te-agent** and the **te-browserbot** have been removed:

   ```
   $ systemctl status te-agent
   Unit te-agent.service could not be found.

   $ systemctl status te-browserbot
   Unit te-browserbot.service could not be found.
   ```

## Delete the Agent from the ThousandEyes Platform

If you have removed this agent with the expectation of replacing it, see [Replacing an Enterprise Agent](https://docs.thousandeyes.com/product-documentation/enterprise-agents/replacing-an-enterprise-agent-using-the-agent-clustering-method).

If you do not plan to replace the agent, you should remove it from the ThousandEyes platform. From the **Network & App Synthetics > Agent Settings** page, expand the agent's row, then click the **More Actions** icon and select **Delete**.

**NOTE:** Deleting an agent will remove it from any tests to which it was assigned, and any tests that have no other agents assigned will be disabled.

![](/files/-M62_PFR3KHYMnGdcVjW)


# Migrating ThousandEyes Appliance or Package-Based Enterprise Agent to Docker

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

There are various reasons why one would want to migrate the deployment method of their [Enterprise Agents](https://docs.thousandeyes.com/product-documentation/enterprise-agents/what-is-an-enterprise-agent). Generally, one of the most frequent nudges towards migration is Enterprise Agent's underlying operating system reaching the [end-of-support stage](https://docs.thousandeyes.com/product-documentation/enterprise-agents/enterprise-agent-support-lifecycle). Our [physical](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-physical-appliance-installation) and [virtual](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-virtual-appliance-installation) appliances and [package-based](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/linux-package-agent-installation) Enterprise Agent deployments are subject to such end-of-support events and require either an in-place upgrade or a migration to a newer and still supported version. Upgrading efforts for appliances and/or package-based agents tend to take a certain amount of effort, but upgrading Docker-based agents is nearly effortless, which makes it an attractive deployment method. Consult the *Why Docker?* section below for details.

This article is a special version of the article that guides you through the [agent replacement by the migration of the agent identity files](https://docs.thousandeyes.com/product-documentation/enterprise-agents/replacing-an-enterprise-agent-using-agent-identity-files). This guide starts by taking the same approach for collecting agent identity files from an existing agent, then continues to explain how to prepare your new Docker-based Enterprise Agent's storage to pick up the identity of your existing agent instead of creating a new one.

In case you have not seen it yet, you are encouraged to review [How to Plan for Enterprise Agent Upgrades](https://docs.thousandeyes.com/product-documentation/enterprise-agents/how-to-plan-for-enterprise-agent-upgrades) - it provides an overview of all possible upgrade paths.

## Why Docker?

Using Docker detaches you from what ThousandEyes [supports as an underlying operating system](https://docs.thousandeyes.com/product-documentation/enterprise-agents/supported-enterprise-agent-operating-systems) for deploying Enterprise Agents. If Docker can run on your x64-based operating system of choice, your Docker-based Enterprise Agent will run on it as well.

Secondly, Docker-based Enterprise Agent deployment is an attractive option because it [cuts down future upgrading efforts significantly](https://docs.thousandeyes.com/product-documentation/enterprise-agents/upgrading-docker-enterprise-agents) - once you have your `docker run ...` command for each agent, the entire upgrade consists of running a few Docker commands - pull the latest image, stop and delete the existing agent container and recreate it with a freshly-download image. Such an upgrade is usually completed in a matter of seconds.

Caveats?

There is only one significant and quite visible disadvantage - virtual and physical ThousandEyes appliances provide an administrative web interface for basic appliance configuration tasks. Such administrative web interface is not provided by the Docker-based agents - Docker-based agents utilize Docker-provided configuration facilities, mainly command line arguments.

## Is There a Simpler Migration Path?

Maybe. As outlined in greater detail in the *Replacement Overview* section of the [Replacing an Enterprise Agent Using Agent Identity Files](https://docs.thousandeyes.com/product-documentation/enterprise-agents/replacing-an-enterprise-agent-using-agent-identity-files) article, you can potentially leverage a simpler method to replace your agents - the [agent clustering method](https://docs.thousandeyes.com/product-documentation/enterprise-agents/replacing-an-enterprise-agent-using-the-agent-clustering-method).

## Migration Guide

The migration consists of five relatively simple steps:

1. Collecting the original agent identity files
2. Determining the new Docker agent's data storage location
3. Placing the collected `*.sqlite` files into the new agent's data storage location
4. Generating and running the `docker run ...` command
5. Wiping the original agent

Read on - the following sections will explain each step with a sufficient amount of details and references to other articles where more related information is provided.

### Step #1a: Collect identity files from an appliance

The process of collecting identity files from an appliance starts with unlocking the appliance. [Unlocking the ThousandEyes Appliance](https://docs.thousandeyes.com/product-documentation/enterprise-agents/unlocking-the-thousandeyes-appliance) article has all the details, but we can summarize the process into two essential steps:

1. Connect to appliance's SSH console
2. Run the `sudo apt-get install te-va-unlock` command

Once the steps above have been completed, the appliance is unlocked. At this point, such appliance can be treated as a Linux package-based Enterprise Agent deployment. Therefore, continue to the Step 1b: Collect identity files from a package-based agent below.

### Step #1b: Collect identity files from a package-based agent

The procedure of collecting identity files from a Linux package-based is described in detail in the *Obtaining Identity Files from the Original Agent* section of the [Replacing an Enterprise Agent Using Agent Identity Files](https://docs.thousandeyes.com/product-documentation/enterprise-agents/replacing-an-enterprise-agent-using-agent-identity-files) article. Here is a short summary of the process:

1. Stop the te-agent service - use `sudo systemctl stop te-agent`
2. Disable the te-agent service - use `sudo systemctl disable te-agent`
3. Move the agent identity files `/etc/te-agent.cfg` and `/var/lib/te-agent/*.sqlite` files to a temporary location, like your SSH user's home directory

At this point, the original agent stops collecting data and checking in with the ThousandEyes platform.

### Step #2: Determine the new Docker agent's data storage location

ThousandEyes' dialog for creating new Docker-based Enterprise Agents provides two input fields that determine the default data storage location for the upcoming Docker agent:

* **Host Vol. Agent Directory** configures the general path prefix under which the container data is stored.
* **Name** value is primarily used to configure the container's name and hostname, but it is also used in the generated storage paths, to make sure each container has its files stored separately.

The two settings listed above are pointed out by #1 and #2 markers in the following figure:

![Docker Enterprise Agent configuration dialog](/files/-M5xtRSKQ9ZLDZKxNO9Z)

The generated `docker run ...` command above contains three paths that retain container's data and are bind-mounted into the container when it is running:

* `/var/lib/te-agent` is the agent state directory, pointed out with #3 above, **the one that we're interested in**
* `/var/lib/te-browserbot` contains [BrowserBot](https://docs.thousandeyes.com/product-documentation/enterprise-agents/what-is-browserbot) data and logs
* `/var/log/agent` contains agent logs

The default `/var/lib/te-agent` path within the container has the following storage path on the host:

```
<HOST_VOL_AGENT_DIR>/thousandeyes/<NAME>/te-agent
```

As an example, let's use the value of `/docker-data` as a Host Vol. Agent Directory and the name `my-new-docker-agent` as the name of the new Docker agent. This would give us the following default agent state storage path:

```
/docker-data/thousandeyes/my-new-docker-agent/te-agent
```

The example path above is the location where the `*.sqlite` identity files collected in Step #1b above should end up in.

### Step #3: Place the \*.sqlite identity files

This step is a relatively simple one:

* Pre-create the Docker agent's `te-agent` storage directory
* Place the `*.sqlite` identity files into the created directory
* Make sure `*.sqlite` files are owned by `root` user and `root` group

Let's reuse the example path from the previous step. To create the target `te-agent` directory, use the `mkdir -p` command:

```
$ sudo mkdir -p /docker-data/thousandeyes/my-new-docker-agent/te-agent
```

Now place the `*.sqlite` identity files into the target directory. If you are converting an existing package-based agent into a Docker-based one on the same host, you can simply use the `mv` tool to move the files. If you are migrating the agent from another host, copy the files to the target host first (i.e. with the `scp` tool), then move them to the final location:

```
$ sudo mv *.sqlite /docker-data/thousandeyes/my-new-docker-agent/te-agent
```

Ensure the proper permissions of the `*.sqlite` files - they need to be owned by the `root` user and `root` group:

```
$ sudo chown root.root /docker-data/thousandeyes/my-new-docker-agent/te-agent/*.sqlite
```

This concludes the transfer of relevant agent state files. Let's continue and transfer the agent configuration settings.

### Step #4: Generate and run the "docker run ..." command

In Step #1b above, the `/etc/te-agent.cfg` file has been collected. Let's inspect its content:

```
$ sudo cat /etc/te-agent.cfg
account-token=<YOUR-ACCOUNT-GROUP-TOKEN-HERE>
crash-reports=1
log-level=DEBUG
log-file-size=10
log-path=/var/log
num-log-files=10
proxy-type=DIRECT
proxy-location=
proxy-user=
proxy-pass=
proxy-bypass-list=
```

The `account-token` setting is generally handled implicitly by the `docker run ...` command generator below. However, pay attention to the `proxy-*` settings - you may need to refer back to their values below.

Now head over to the **Network & App Synthetics > Agent Settings** section of the ThousandEyes web portal, click the **Add New Enterprise Agent** button and switch to the **Docker** tab. The familiar Docker agent creation dialog should appear:

![Docker Enterprise Agent configuration dialog - a filled-out example](/files/-M5xtRSP-UnnVvZnBlCZ)

You should fill in all the necessary details - **Nam**e (1), a designated and absolute **Host Vol. Agent Directory** (2) path. If your original agent's `proxy-*` settings were configured, manipulate the proxy-related section of the dialog (3) to reach the identical proxy configuration.

On the right-hand side, the full `docker run ...` command will be generated (4). Pay particular attention to the `/var/lib/te-agent` directory's storage path on the host (5) - the path should be identical to the one pre-created in Step #3 of this guide.

For additional information about deploying Docker Enterprise Agents, consult the [Docker-Based Enterprise Agent Deployment Guide](https://docs.thousandeyes.com/product-documentation/enterprise-agents/enterprise-agent-deployment-using-docker).

Once you're satisfied with the generated `docker run ...` command, run it on your new host. Continuing with the existing example, the following commands should be run to create and start the new Docker agent:

```
$ docker pull thousandeyes/enterprise-agent > /dev/null 2>&1
$ docker stop 'my-new-docker-agent' > /dev/null 2>&1
$ docker rm -v 'my-new-docker-agent' > /dev/null 2>&1
$ docker run \
  --hostname='my-new-docker-agent' \
  --memory=2g \
  --memory-swap=2g \
  --detach=true \
  --tty=true \
  --shm-size=512M \
  -e TEAGENT_ACCOUNT_TOKEN=<REDACTED> \
  -e TEAGENT_INET=4 \
  -v '/docker-data/thousandeyes/my-new-docker-agent/te-agent':/var/lib/te-agent \
  -v '/docker-data/thousandeyes/my-new-docker-agent/te-browserbot':/var/lib/te-browserbot \
  -v '/docker-data/thousandeyes/my-new-docker-agent/log/':/var/log/agent \
  --cap-add=NET_ADMIN \
  --cap-add=SYS_ADMIN \
  --name 'my-new-docker-agent' \
  --restart=unless-stopped \
  thousandeyes/enterprise-agent /sbin/my_init
```

Once the command above returns, you should see your new agent container running. You can inspect the Docker containers' state with the `docker ps` command.

In the ThousandEyes web portal, you should see your original agent checking in again, and data collection for tests assigned to this agent will be restarted. If you expand the agent, you'll notice the agent's reported **Installation Type** changed to `Docker`.

### Step 5 (optional): Install CA certificates

If custom CA certificates were installed on your original agent, install them on your new Docker-based agent as well. On appliances, you can find installed CA certificates in the **Network > CA Certificate** section of the administrative web interface. Consult the [guide for installing CA certificates on Enterprise Agents](https://docs.thousandeyes.com/product-documentation/enterprise-agents/installing-ca-certificates-on-enterprise-agents) for more information.

### Step 6 (optional): Migrate SSH keys

Virtual and physical appliances may have multiple SSH keys installed on them that you may want to migrate over to your new Docker host. Head over to the **Appliance Access** section of the appliance's administrative web interface and review the list of installed SSH keys.

### Step 7: Wipe the original agent

As an extra precautionary measure, all ThousandEyes software, configuration and state information should be removed from the original agent.

**WARNING: This action is irreversible.** After the following command is executed, if something unexpected happens to your replacement agent and unless you have other means of restoring the agent state files (out-of-band backup), you will not be able to recover agent state files. However, if your replacement agent is already running and communicating with the platform, you most likely have nothing to worry about.

On Ubuntu systems and ThousandEyes appliances, the following command wipes all ThousandEyes agent-related software, configuration and state files:

```
$ sudo apt-get purge te-agent te-browserbot
```

On RHEL-based systems use the following command to achieve the same effect:

```
$ sudo yum remove te-agent te-browserbot
```

That's it. Great success! You've successfully migrated your non-Docker agent to a Docker-based one.

## Questions?

If you have any questions regarding the migration procedure, or if you get stuck at some point in the migration process, [contact the ThousandEyes Customer Engineering team](https://docs.thousandeyes.com/product-documentation/getting-started/getting-support-from-thousandeyes) and we'll help you out.


# Enterprise Agent Utilization

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

For ThousandEyes Enterprise Agents and agent clusters, the Utilization metric is not a measure related to any system hardware resource, such as random-access memory (RAM) use or CPU time consumed.

Enterprise Agent utilization is a measure of time taken to execute tests within a given queue. Tests in a queue must be completed before the next round of tests must begin. Utilization below 100% represents available time to accommodate more tests or for existing tests to take longer to complete. Because the majority of time for a test to execute is dependent on network or server response time, adding hardware resources such as RAM, faster or more CPU's or faster I/O hardware to the system running the Enterprise Agent is generally not effective in reducing utilization, assuming the [hardware requirements for Enterprise Agents](https://docs.thousandeyes.com/product-documentation/enterprise-agents/enterprise-agent-hardware-requirements) have been met.

Most queues execute tests with varying degrees of concurrency, but place limits on the number of concurrent tests in order to ensure that customers' networks are not over-utilized and to ensure that tests do not interfere with each other.

## Displaying Agent Utilization

Agent utilization is displayed in both the ThousandEyes application (web interface) and is available from the ThousandEyes API. Utilization is calculated at 5-minute intervals.

### Utilization in the ThousandEyes application

The **Agents** tab of the Enterprise Agents page (**Network & App Synthetics > Agent Settings > Enterprise Agents**) provides a table with each Enterprise Agent that is visible in the current account group context. Each row in the table lists an Enterprise Agent, along with a single percentage in the **Utilization** column. The single percentage displayed is the largest of the percentages from the queues which are used by the agent. When hovering over the agent utilization percentage there is further context on utilization consumed by other test types.

![](/files/-M8rzTUK5VgKS9nqcNWt)

Expanding an agent row and clicking the **Agent Statistics** tab displays graphs of all **Agent Utilization** queues used, with data for upto the past 30 days with default at Last 24 hours. You can also view the currently assigned tests on that agent including average and maximum utilization consumed by each test over the selected time period.

![](/files/-M8rzTUPmRhbCq9LoAiC)

In the example above, the Enterprise Agent "Branch - San Jose (EA1)" has three active queues, of which the **Bandwidth** queue currently has the greatest utilization of 38%. Below is a table of all queue types and their associated tests.

Up to four queues may be displayed:

| Queue Name | Test Types Assigned to Queue                                                                    |
| ---------- | ----------------------------------------------------------------------------------------------- |
| Browser    | <ul><li>Page Load tests</li><li>Transaction tests</li></ul>                                     |
| General    | <ul><li>All Network Layer tests</li><li>All DNS Layer tests</li><li>HTTP Server tests</li></ul> |
| Bandwidth  | <ul><li>All tests with Bandwidth metrics</li><li>All tests with Throughput metrics</li></ul>    |
| Voice      | <ul><li>All Voice Layer tests</li></ul>                                                         |

The **Agent Utilization** section displays only those queues in which the agent is currently running tests, or has run within the past 24 hours. For example, if the Enterprise Agent is only running agent-to-agent tests with Throughput enabled, the Bandwidth and Throughput queue is displayed. The other queues are not displayed.

Utilization percentage in a queue is independent of utilization in other queues. For example, high utilization in the Browser queue will not affect utilization in the other three queues.

## Cluster Utilization

Utilization for an Enterprise Agent cluster is displayed as a percentage on the row of the cluster in the **Clusters** tab of the **Enterprise Agents** page. The utilization of a given queue represents the most heavily used queue of any member in the cluster, for that queue type.

### Utilization in the ThousandEyes API

The ThousandEyes API provides the [/agents](https://developer.cisco.com/docs/thousandeyes/v7/#!agents-api-overview) endpoint. When specifying an Agent ID, the output of this endpoint will provide the utilization percentage from the queue with the highest utilization percentage on that Enterprise Agent or cluster. In the example above, if the Enterprise Agent "vm2-xen-stl" has Agent ID 966, then the following query:

```
https://api.thousandeyes.com/v7/agents/966
```

would produce output that included the "utilization" field and the aforementioned percentage:

`"utilization": 21`

For more information on using the API, see the [ThousandEyes API documentation](https://developer.cisco.com/docs/thousandeyes/v7/).

Data from polling the API for Enterprise Agent utilization can be used by customers to create alerting mechanisms when Agent utilization reaches a threshold.

## High Utilization

Utilization percentage ranges from 0% (no tests in a queue) to 100%. At 100% utilization, tests may not complete before the next round's tests would normally start. The typical symptom is missing data in one or more Views within a test, either intermittently or consistently, depending on the severity of the high utilization. Review the sections below to identify causes of high utilization and the corresponding solutions.

### Identifying the Causes

High utilization may be caused by one or a number of long-running tests, or may be due to smaller contributions from a large number of tests, or some combination of the two. Long-running tests are tests which fail to complete before reaching their Timeout value, or tests whose completion time is a significant fraction of the test’s Timeout setting, particularly if the Timeout setting has been increased from the default value. Test targets which fail to respond are a common reason for a test to reach their Timeout time. The larger the amount of time taken by a test, the greater the contribution to the utilization for the test's queue.

Alternatively, high utilization may be caused by large numbers of tests, none of which are long-running. There is no single number of tests in a queue which will cause high utilization - the threshold varies by queue and test characteristics.

To determine the cause(s) of high utilization in a queue, perform the steps below:

1. Locate tests belonging to that queue type (see table above) which have long run times. Ways to locate long-running tests include:
   * Check all of the test's Views for missing data, or for long completion times (metric depends on test type: HTTP Server tests use "Response Time"; Page Load tests use "Page Load time", DNS Server tests use "Resolution Time", etc...)
   * Determine (using either the Utilization graph or the API) the date when utilization increased, then use the Activity Log or a test's **Modified** date to identify tests created or modified around that time.
   * Creating a report under the Reports function to display test completion time, either numerically or graphically.
2. Temporarily disable the test with the longest run time by unchecking the box in the **Enabled** column on the [Test Settings](https://app.thousandeyes.com/network-app-synthetics/test-settings/) page.
3. Observe the Utilization for the next two rounds of new utilization data.
4. If a test is identified as contributing to high utilization, check for tasks within the test which may be the source of the utilization.
   * If a test includes the **Perform Bandwidth measurements** setting, uncheck this setting and observe two rounds of Utilization data.
   * If a test includes the **Perform Network measurements** setting (for End to End Metrics and Path Visualization), uncheck this setting and observe two rounds of Utilization data.
   * If a test includes the **Enable Throughput** setting, uncheck this setting and observe two rounds of Utilization data.
5. If the Utilization does not decrease after completing the previous steps, repeat the steps for another test with a long run time. Do not re-enable any tests that have already been disabled.
6. Continue to disable tests until Utilization drops.
7. If the cause is not identified after these steps, check your organization's tools that may be sending requests to the ThousandEyes API to run Instant Tests, and check your firewall and other logs for api.thousandeyes.com or its IP address.

Alternatively, the reverse approach can be used: disable a large number of tests and then begin adding tests until you see Utilization increase. This approach may be better if no long-running tests can be identified, per Step 1.

Note that spikes in utilization (as opposed to prolonged high utilization) may be caused by Instant Tests that are long running. Instant Tests can be initiated through the web interface or the API. You can use the [Activity Log](https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/working-with-the-activity-log) to check for Instant Tests run at the same time as a utilization spike. For the API, check for connections to <https://api.thousandeyes.com> from your network, or contact the [Customer Engineering team](mailto:support@thousandeyes.com) to identify individual users of the API.

### Solutions

Once you have made a determination as to whether high utilization is caused by a small number of long-running tests or a large number of tests that complete within normal times or a mix of the two conditions, you can employ one or more of the following options:

* Deploy additional Enterprise Agents If additional Enterprise Agent licenses are available with your ThousandEyes subscription, or your organization has a "pay as you go" subscription, then deploy one or more new Enterprise Agents, preferably in an [Agent cluster](https://docs.thousandeyes.com/product-documentation/enterprise-agents/working-with-enterprise-agent-clusters). This is the best solution when a large number of tests are the source of high utilization.
* Reduce the frequency of long-running tests Changing the test interval from a 2-minute or 5-minute frequency to 10, 15 or 30 minutes can reduce utilization. Optionally, it may be possible to configure an Alert Rule to notify customers when the root cause is no longer present, and a shorter test interval safe to use.
* Reduce the Timeout setting on tests that often time out, particularly if the test is run at 2- or 5-minute frequency.
* Address the root causes of long-running tests Using test data and other any other resources available, determine why a test takes significant time to complete. Common root causes include:
  * Targets that are unresponsive
  * Transaction tests that timeout due to missing elements
  * Page Load tests that timeout due to missing objects
  * Excessive Bandwidth testing of the same target or multiple targets
* Disable long-running tests
* Reduce use of Instant Tests via the API
* Remove consistently failing tests, as they constantly take the whole test timeout length to execute.


# Proxy Environments


# Installing Enterprise Agents in Proxy Environments

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

Some organizations' security policies require web communication (HTTP, HTTPS and FTP) from internal networks to the Internet be sent through a proxy server, in order to inspect and control the communication. Installation of an Enterprise Agent requires varying degrees of internet access, depending on the type of Enterprise Agent being installed. Additional or different installation steps may be required to install an Enterprise Agent when a proxy server is required for internet access.

## Types of Proxy Server

Proxy servers have two principle characteristics which govern the way clients are configured:

* **Explicit or transparent** Proxy servers which require each client to be configured with the proxy's IP address (or hostname) and port number, and (optionally) user credentials, are called explicit proxies. Proxies which do not require clients to be configured with proxy information are called transparent proxies.
* **SSL decrypting or non-SSL decrypting** Proxy servers which perform SSL/TLS decryption require each client to be configured with the proxy's CA certificate (sometimes called a signing certificate or root certificate). Non-SSL decrypting proxies do not require clients to be configured with a CA certificate.

The figure below indicates the required configuration information for each of the four combinations of proxy type:

![](/files/-M62_O3dVWrgFMLytGIR)

For proxies that are transparent and non-SSL decrypting, no additional configuration is required to perform the Enterprise Agent installation. Follow the installation instructions for your type of Enterprise Agent installation without a proxy.

The remaining three configurations of proxy are referred to in the remainder of this document with the following letters :

* **A:** Explicit, SSL decrypting proxy configuration
* **B:** Explicit, non-SSL decrypting proxy configuration
* **C:** Transparent, SSL decrypting proxy configuration

Consult with your proxy or network administrator to determine which type of proxy you have, and obtain all required information before proceeding.

## Types of Agent Deployment

* Deploying a Linux package agent
* Deploying a Docker agent
* Deploying an appliance

## Deploying a Linux Package Agent

Deploying a Linux package Agent is performed by downloading and running the install\_thousandeyes.sh shell script. The instructions for downloading and running the script are found by going to the **+ Add New Agent** form of the **Network & App Synthetics > Agent Settings > Enterprise Agents** page, and selecting "Linux Package" for the **Package Type**, then clicking the **Show Advanced Options** link. The instructions are reproduced below:

```
curl -Os https://downloads.thousandeyes.com/agent/install_thousandeyes.sh
chmod +x install_thousandeyes.sh
sudo ./install_thousandeyes.sh -b <ACCOUNT-TOKEN>
```

In the first line, the curl command is used to download the install\_thousandeyes.sh file. The curl command may require additional flags to use the proxy.

In the third line, the install\_thousandeyes.sh script is executed. The script runs the Linux system's package management tool (if Ubuntu, the APT package manager; if Red Hat/CentOS/Oracle Linux, the YUM package manager) to download and install the Enterprise Agent software packages. To download and install the Agent through the proxy, the APT or YUM configuration file must be edited to include proxy information. Then the script configures the installed Agent. The script may require additional command line flags to use the proxy.

The following configuration steps may be required:

1. Install the proxy server's CA certificate
2. Configure the system package manager to use the proxy server
3. Run the **curl** command with modified flags
4. Run the **install\_thousandeyes.sh** script with modified flags

For proxy configuration A, B, or C, use the following table of steps:

| Proxy Configuration | Perform the following configuration steps                                                                                                                                              |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A                   | 1, 2, 3, 4                                                                                                                                                                             |
| B                   | 2, 3, 4                                                                                                                                                                                |
| C                   | 1, then [standard Linux package installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/linux-package-agent-installation) |

#### 1. Install the proxy server's CA certificate

Depending on a customer's process for installing new systems, the proxy's CA certificate may not be installed by default. If the certificate is not pre-installed, the procedure to add a CA certificate to a Linux system with an Enterprise Agent is provided in the article [Installing CA Certificates on Enterprise Agents](https://docs.thousandeyes.com/product-documentation/enterprise-agents/installing-ca-certificates-on-enterprise-agents). Select either the [Ubuntu](https://docs.thousandeyes.com/product-documentation/enterprise-agents/installing-ca-certificates-on-enterprise-agents#ubuntu) or the [Red Hat Enterprise Linux / CentOS / Oracle Linux](https://docs.thousandeyes.com/product-documentation/enterprise-agents/installing-ca-certificates-on-enterprise-agents#red-hat-enterprise-linux-centos-and-oracle-linux) section.

**IMPORTANT:** Only install the CA certificate into the system CA certificate store. Do not perform the BrowserBot CA certificate installation, as the BrowserBot package is not yet installed.

#### 2. Configure the package manager to use the proxy server

The install\_thousandeyes.sh script runs the system's package manager (APT or YUM) to download and install Agent packages. Additionally, the package manager will be used to automatically update the Agent packages and perform essential operating system updates. The procedure to configure the system package manager to use the proxy server is provided in the article [Configuring an Enterprise Agent to use a proxy server](https://docs.thousandeyes.com/product-documentation/enterprise-agents/configuring-an-enterprise-agent-to-use-a-proxy-server). Select either the [Ubuntu](https://docs.thousandeyes.com/product-documentation/enterprise-agents/configuring-an-enterprise-agent-to-use-a-proxy-server#configuring-proxy-settings-for-the-apt-package-manager-on-ubuntu) or [RHEL/CentOS/Oracle Linux](https://docs.thousandeyes.com/product-documentation/enterprise-agents/configuring-an-enterprise-agent-to-use-a-proxy-server#configuring-proxy-settings-for-the-yum-package-manager-on-rhel-centos-oracle-linux) section.

The proxy used by the package manager need not be the same proxy used for the main Agent processes. Alternatively, if all needed repositories are mirrored on the internal network, or if communication to standard repositories on the Internet is permitted without a proxy, then this step can be skipped.

#### 3. Run the curl command with modified flags

Modify the curl command to use flags for the proxy name or IP address and port number, and optionally a username and password:

```
curl \
  -x <PROXY IP ADDRESS or HOSTNAME>:<PROXY PORT> \
  -U <USERNAME>:<PASSWORD> \
  -Os https://downloads.thousandeyes.com/agent/install_thousandeyes.sh
```

Depending on the characters used in the username and password, the `<USERNAME>:<PASSWORD>` string may need to be enclosed in double-quotes to avoid being interpreted by the shell.

#### 4. Run the install\_thousandeyes.sh script with modified flags

Run the chmod command to make the script executable. Then, with the proxy name or IP address and port number, and optionally a username and password, modify the script command's flags:

```
chmod +x install_thousandeyes.sh
sudo ./install_thousandeyes.sh \
  -b \
  -t STATIC \
  -P <PROXY IP ADDRESS or HOSTNAME>:<PROXY PORT> \
  -U <USERNAME> \
  -u <PASSWORD> \
  <ACCOUNT TOKEN>
```

The script will install the Enterprise Agent and the optional BrowserBot component. Omit the -b flag if BrowserBot is not required. The script will also configure the /etc/te-agent.cfg file with the proxy information provided by the command's flags.

Alternatively, if the Enterprise Agent will use a PAC file to select its proxy, then modify the script command for the PAC file:

```
chmod +x install_thousandeyes.sh
sudo ./install_thousandeyes.sh \
  -b \
  -t PAC \
  -P <PAC FILE URL> \
  -U <USERNAME> \
  -u <PASSWORD> \
  <ACCOUNT TOKEN>
```

To see all the supported command line flags of the script, use the --help flag:

```
./install_thousandeyes.sh --help
```

**NOTE:** Authentication to the proxy is performed via the HTTP Basic authentication mechanism, including CONNECT method requests for subsequent HTTPS-based requests. Basic authentication credentials are sent in clear text, encoded in Base64. Organizations which do not allow any credentials to be transmitted on a network in clear text should consider alternatives to credential-based authentication to the proxy, such as configuring the proxy to allow-list Enterprise Agents via their IP addresses.

## Deploying a Docker Agent

Deploying a Docker Enterprise Agent is performed by running a series of docker commands on the Docker host. The commands are created by going to the **+ Add New Agent** form of the **Network and App Synthetics > Agent Settings > Enterprise Agents** page, and selecting "Docker" for the **Package Type**, then filling out the form.

The following configuration steps may be required:

1. Install proxy server's CA certificate on the Docker host.
2. Configure Docker to use the proxy server.
3. Create Enterprise Agent Docker container with proxy configuration.
4. Mount proxy server's CA certificate in the Enterprise Agent container.

For proxy configuration A, B or C use the following table of steps:

| Proxy Configuration | Perform the following configuration steps                                                                                                                 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A                   | 1, 2, 3, 4                                                                                                                                                |
| B                   | 2, 3, 4                                                                                                                                                   |
| C                   | 1, then [standard Docker installation](https://docs.thousandeyes.com/product-documentation/enterprise-agents/enterprise-agent-deployment-using-docker), 4 |

### 1. Install proxy server's CA certificate on the Docker host

Depending on a customer's process for installing new systems, a Docker host may not have the proxy's CA certificate installed by default. If the required certificate is not pre-installed, the procedure to add a CA certificate to a Linux system acting as the Docker host is provided in the article [Installing CA Certificates on Enterprise Agents](https://docs.thousandeyes.com/product-documentation/enterprise-agents/installing-ca-certificates-on-enterprise-agents). Select either the [Ubuntu](https://docs.thousandeyes.com/product-documentation/enterprise-agents/installing-ca-certificates-on-enterprise-agents#ubuntu) or the [Red Hat Enterprise Linux / CentOS / Oracle Linux](https://docs.thousandeyes.com/product-documentation/enterprise-agents/installing-ca-certificates-on-enterprise-agents#red-hat-enterprise-linux-centos-and-oracle-linux) section.

For other Linux distributions or non-Linux Docker hosts, consult your operating system documentation for more information on adding CA certificates to your system's certificate store, or contact the ThousandEyes Customer Engineering team.

**IMPORTANT:** Only install the CA certificate into the system CA certificate store. Do not perform the BrowserBot CA certificate installation.

### 2. Configure Docker to use the proxy server

This procedure configures the Docker commands to use the proxy server when communicating to servers on the internet.

**2.1 Red Hat Enterprise Linux / CentOS / Rocky Linux / Oracle Linux**

Create the /etc/systemd/system/docker.service.d directory:

```
sudo mkdir -p /etc/systemd/system/docker.service.d
```

Edit the file in which then Docker proxy configuration will be stored:

```
sudo nano /etc/systemd/system/docker.service.d/proxy.conf
```

Enter the following environment variable configuration, replacing the sample values shown below with your proxy configuration information:

```
[Service]
Environment="HTTP_PROXY=http://user:pass@10.1.2.32:3128/"
Environment="HTTPS_PROXY=http://user:pass@10.1.2.32:3128/"
```

Reload the systemd configuration:

```
sudo systemctl daemon-reload
```

Restart the Docker service (warning, this command restarts all running Docker containers):

```
sudo systemctl restart docker
```

Verify whether the newly configured environment variables HTTP\_PROXY and HTTPS\_PROXY have the correct values:

```
sudo systemctl show --property=Environment docker
```

Download the Docker image using the docker pull command:

```
docker pull thousandeyes/enterprise-agent
```

**2.2 Ubuntu**

Edit the file in which the Docker proxy configuration will be stored:

```
sudo nano /etc/default/docker
```

Append the following content, replacing the sample values shown below with your proxy configuration information:

```
export  "http_proxy=http://user:pass@10.1.2.32:3128/"
export "https_proxy=http://user:pass@10.1.2.32:3128/"
```

Restart the Docker service (NOTE: this command restarts all running Docker containers):

```
sudo restart docker
```

Download the Docker image using the docker pull command:

```
docker pull thousandeyes/enterprise-agent
```

### 3. Create Enterprise Agent Docker container with proxy configuration

Log in to the ThousandEyes web application and open the **Network & App Synthetics > Agent Settings > Enterprise Agents** page. The commands to create the Enterprise Agent Docker container are produced by opening **+ Add New Agent** form and selecting "Docker" for the **Package Type**, then by completing the form. An example of the completed form is below:

![](/files/xtBD4xGfCGYU7QQvEtNr)


# Configuring an Enterprise Agent to Use a Proxy Server

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

Some organizations' security policies require web communication from internal networks to the Internet be sent through a proxy server, in order to inspect and control the communication. Additionally, organizations may deploy proxies for web caching, which can improve web browsing performance and reduce network congestion.

This article provides background information on web proxy servers, and steps to configure proxy server settings on an existing Enterprise Agent. If you have not yet installed an Enterprise Agent, and are in an environment that requires a proxy server to access the Internet, you should first read [Installing Enterprise Agents in Proxy Environments](https://docs.thousandeyes.com/product-documentation/enterprise-agents/installing-enterprise-agents-in-proxy-environments) to ensure that the installation can be done through a proxy.

Proxies for voice tests are not configured using the information in this article. If you need configuration information for Voice over IP communication proxies, see [SIP Server Test Settings](https://docs.thousandeyes.com/product-documentation/tests/voice-tests#manually-configuring-sip-server-tests).

## Introduction

Configuring a proxy on an Enterprise Agent depends on a number of variables. The type of proxy server will affect the configuration of the Enterprise Agent. Additionally, the type of Agent deployment used (Appliance, Docker container or Linux package) will affect the configuration process. Additionally, proxy configuration may need to be performed both for the Enterprise Agent's software, and for the system's package manager which performs software updates. Before attempting to configure the Enterprise Agent, customers should read this Introduction to determine what information will be required. Then proceed to the section(s) which contains configuration steps needed for your environment.

### Types of Proxy Server

Proxy servers have two principle characteristics which govern the way clients are configured:

* **Explicit or transparent**\
  Proxy servers which require each client to be configured with the proxy's IP address (or hostname) and port number, and (if required) user credentials, are called explicit proxies. Clients open a TCP/IP-based connection to the proxy. The proxy initiates a second TCP/IP connection to the server.

  Clients connecting to explicit proxies use the same [HTTP methods](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) (GET, POST, HEAD, etc...) for http URLs as with a direct connection to the server. For https URLs, the client issues an HTTP CONNECT method which indicates to the proxy that data in subsequent packets from the client should be transferred directly into the data of packets sent to the server, at a specified domain name or IP address, and TCP port number. In subsequent packets, information including the actual HTTP request method and other request data (headers and body) can be sent through the proxy, even when encrypted with SSL/TLS.

  Proxies which do not require clients to be configured with proxy information are called transparent proxies. Clients make HTTP requests as if the connection were direct to the server. The transparent proxy, perhaps with the help of other network equipment (routers using [WCCP](https://en.wikipedia.org/wiki/Web_Cache_Communication_Protocol), policy-based routing, layer 4 switching, or similar infrastructure) intercepts client packets and performs some amount of inspection and possibly alteration of the packet.
* **SSL decrypting or non-SSL decrypting**\
  For https URLs, a proxy server may decrypt the data in the packet to perform inspection of the contents. Proxy servers which perform SSL/TLS decryption are sometimes called man-in-the-middle (MITM) proxies. Each client using the proxy must be configured with the proxy's CA certificate (also referred to as a signing certificate or root certificate). The CA certificate is used by the proxy to decrypt and re-encrypt data between the server and the client. To do this, the proxy re-writes the SSL server certificates to appear to have been issued by the proxy's CA certificate, The CA certificate is used by the client to verify SSL server certificates that have passed through the proxy re-write process.

  Non-SSL decrypting proxies do not require clients to be configured with a proxy CA certificate.

The figure below indicates the required configuration information for each of the four combinations of proxy type:

![](/files/-M62_WeLKrO263d_MU-J)

For proxies that are transparent and non-SSL decrypting, no additional configuration in this article is required for the Enterprise Agent. Configure your Enterprise Agent in the same way that non-proxied Enterprise Agents are configured.

For proxies that are transparent and perform SSL decryption, skip to the last section in this article, Installing Proxy CA Certificates.

The remaining two types of proxy (explicit SSL decrypting and explicit non-SSL decrypting) require configuration based on the configuration method and type of deployment (appliance, Docker container, or Linux package).

### Configuration Methods

When using explicit proxies (types A and B), an Enterprise Agent can obtain its proxy information using one of two methods: static configuration or a use a proxy auto-configuration file or "PAC" file.

* **Static**: The agent is configured with information that is static - the agent will use the same proxy information - a single proxy IP address (or hostname) and port number - for every request. The configuration information is read at agent start-up from a local configuration file, and whenever the **te-agent** process is restarted.
* **PAC file**: The agent uses a downloaded file of rules to dynamically obtain proxy information. A PAC file contains JavaScript that selects a proxy IP address (or hostname) and port (or selectes no proxy) for each request, based on variables such as the domain of the web server, the IP address of the client, or a string contained in the path of the URL. For more information on PAC files, see [Writing and Testing Proxy Auto-Configuration (PAC) Files](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/proxy/writing-and-testing-proxy-auto-configuration-pac-files). PAC files are downloaded and read by the Enterprise Agent at startup, and whenever the te-agent process is restarted.

The table below indicates which types of Enterprise Agent deployment support these configuration methods.

|                               | STATIC    | PAC         |
| ----------------------------- | --------- | ----------- |
| Virtual or Physical Appliance | supported | supported\* |
| Docker container              | supported | supported\* |
| Linux Package                 | supported | supported\* |

**\*** The PAC file method will not configure the Enterprise Agent's package manager, which performs automatic package updates for the operating system and Thousandeyes software. Proxy configuration for the APT package manager (Appliances and Ubuntu-based Linux package), APK package manager (Docker container), or the YUM package manager (Red Hat Enterprise Linux, CentOS and Oracle Linux installations) must be done separately with static proxy configuration.

### Additional Configuration Information

In addition to IP address (or hostname) and port number, the following configuration information may be required.

* Static configuration

  **Bypass list:** A list of domain names, IP addresses or networks to which each request will be compared. A request which matches an entry in the list is sent directly to the web server, rather than sent through the proxy. Multiple list entries are separated by semi-colons (no whitespace). The \* wildcard is permitted with trailing domain name expressions, such as \*.example.com, which would match [www.example.com](http://www.example.com) and [www.us.example.com](http://www.us.example.com). Similarly, \*example.com would match the previous two domain names plus myexample.com, [www.myexample.com](http://www.myexample.com) and [www.us.myexample.com](http://www.us.myexample.com). Networks can be specified by CIDR notation, such as 192.168.1.0/24.

  **NOTE:** DNS resolution is **not** performed on the domain name in a request, in order to check the resulting IP address(es) against addresses or networks in the bypass list. Only requests specified by IP address can match IP addresses or networks in the bypass list.
* PAC file configuration

  **PAC file location:** The URL that the Enterprise Agent will use to download the PAC file when the Agent is booted. PAC files are typically downloaded from a web server, but can also be installed on the Enterprise Agent's local file system and accessed using a file: URL.
* Static and PAC file configurations
  * **Username and password:** If a proxy requires authentication, the Enterprise Agent must be configured with a username and password. Username may be in the form of a simple username, an email address or Windows domain\username. This set of credentials will be sent to a proxy whenever that proxy requires authentication. This includes both test requests and administrative requests (downloading configuration and uploading data to/from ThousandEyes, software updates from package repositories, etc...).

    **NOTE:** Authentication to the proxy is performed via the HTTP Basic authentication mechanism, including CONNECT method requests for subsequent HTTPS-based requests. Basic authentication credentials are sent in clear text, encoded in Base64. Organizations which do not allow any credentials to be transmitted on a network in clear text should consider alternatives to credential-based authentication to the proxy, such as configuring the proxy to allow-list Enterprise Agents via their IP addresses.
  * **Package repository proxy**: For accessing an APT or YUM package repository, an organization may use a different proxy than the one used by the Agent's other functions. If so, a second proxy IP address (or hostname) and port is required.

### Next Steps

If needed, consult with your proxy or network administrator to determine which type of proxy you have (A, B or C) and what configuration method (static or PAC file) is used, and any additional configuration information needed, per the sections above. Then proceed to the configuration instructions for the type of Enterprise Agent (Appliance, Docker container, or Linux package) being deployed.

## 2. Docker Container Enterprise Agents

Enterprise Agents deployed as Docker containers should have proxy settings configured [during the container creation](https://docs.thousandeyes.com/product-documentation/enterprise-agents/installing-enterprise-agents-in-proxy-environments#deploying-a-docker-agent). If a Docker Enterprise Agent that has been deployed requires a change to proxy settings, reinstall the container image with a new container that is configured with the new proxy settings and with other settings identical to the original container.

### Reconfigure Proxy Settings for an Existing Enterprise Agent

If an existing agent is being reconfigured with new proxy settings, the following is required:

1. The existing Enterprise Agent container must be stopped and removed before creating it again. To stop the Docker-based Enterprise Agent, use the following command:

   ```
   docker stop my-proxied-agent
   docker rm -v my-proxied-agent
   ```
2. The newly created `docker run` command must contain the same hostname (`--hostname`) and host volume directory location (`-v`) configuration parameters. Otherwise, the `docker run` command will create a new Enterprise Agent.

   See the *Reinstalling the Enterprise Agent* section of [Enterprise Agent Deployment Using Docker](https://docs.thousandeyes.com/product-documentation/enterprise-agents/enterprise-agent-deployment-using-docker) for information on reloading Docker images for an existing Docker container Enterprise Agent.

To create the new docker run command with proxy settings, go to the **+ Add New Agent** form of the **Network & App Synthetics > Agent Settings > Enterprise Agents** page, and select "Docker" for the **Package Type.** Then select "Static" or "PAC" for the **Proxy Type**, and complete the form.

### Static Configuration

An example of a completed form for static proxy configuration is below:

![](/files/xtBD4xGfCGYU7QQvEtNr)

For information on the **Name**, **Docker Version** and **Host Vol. Agent Directory** fields, see [Enterprise Agent Deployment Using Docker](https://docs.thousandeyes.com/product-documentation/enterprise-agents/enterprise-agent-deployment-using-docker).

The **Proxy Host** and **Proxy Port** are required. **Proxy User**, **Proxy Password** and **Proxy Bypass List** are optional.

Static proxy configuration applies the proxy settings to the Enterprise Agent processes, and to the package manager system updates.

### PAC File Configuration

An example of the completed form for PAC file configuration is below:

![](/files/-M62_WebTtqQk5hFdMFH)

For information on the **Name**, **Docker Version** and **Host Vol. Agent Directory** fields, see [Enterprise Agent Deployment Using Docker](https://docs.thousandeyes.com/product-documentation/enterprise-agents/enterprise-agent-deployment-using-docker).

The **PAC File URL** is an http: or https: URL for a PAC file that is loaded from a remote web server, or a file: URL for a PAC file installed on the local file system (see the *PAC File Stored on Docker Agent* section below). The **PAC File URL** is required.

**Proxy User** and **Proxy Password** are optional.

**NOTE:** The PAC file is loaded from the URL provided when the Enterprise Agent container is started. If the PAC file is updated, container restart is required for the new PAC file to be loaded again.

**PAC File Stored on Docker Agent**

A Docker Enterprise Agent can use a PAC file installed locally on the Docker host, and retrieved via a file: URL rather than downloading the PAC file from a web server. A local PAC file can be configured by placing the PAC file on the Docker host persistent host volume directory, created with the -v flag of the docker run command. For example, if the persistent host volume directory is created with:

```
-v /storage
```

then the container can be created or recreated with the following command (only relevant flags are shown):

```
docker run \
 ...
 -e TEAGENT_PROXY_TYPE=PAC \
 -e TEAGENT_PROXY_LOCATION='file:///var/lib/te-agent/proxy.pac' \
 ...
 -v '/storage/thousandeyes/<AGENT HOSTNAME>/te-agent':/var/lib/te-agent \
 ...
```

Note the use of triple forward slash in the file: URL above. Then after running the docker run command to create the container, create a PAC file in the following location:

```
/storage/thousandeyes/<AGENT HOSTNAME>/te-agent/proxy.pac
```

Once the container starts, the PAC file will be read from local storage, without requiring a web server. The PAC file can be edited from the Docker host.

**NOTE:** The PAC file is loaded from the URL provided when the Enterprise Agent container is started. If the PAC file is updated, container restart is required for the new PAC file to be loaded again.

#### Configuring Proxy Settings for the Package Manager

Additionally, for Docker-based Enterprise Agents the package manager's proxy configuration must be configured statically if the ThousandEyes package downloads must be proxied. Static proxy configuration must be added to the docker run command using `-e` flags for environment variables, as illustrated below:

```
 -e REPO_PROXY_LOCATION='<PROXY HOST or IP ADDRESS>:<PROXY PORT>' \
 -e REPO_PROXY_USER='<PROXY USER>' \
 -e REPO_PROXY_PASS='<PROXY PASSWORD>' \
```

Copy the commands from the completed form and add the above commands to the `docker run` command, then run the commands on the Docker host.

## 3. Configure Proxy Settings on Virtual Appliances

Proxy settings on ThousandEyes Enterprise Agent Virtual and Physical Appliance can be configured at any time from the Network tab of the web administrative interface on the Appliance. A proxy for the Enterprise Agent and a proxy for the [APT](https://en.wikipedia.org/wiki/Advanced_Packaging_Tool) package manager can be configured independently. Using a web browser, navigate to `http://<APPLIANCE.IP.ADDRESS.HERE>` and log in, then click on the **Network** menu item (1) as shown in the following image:

![](/files/-M62_Wejp3Xyfhl8DmTq)

### Configuring Proxy Settings for Web Proxy

Scroll down to the **Web Proxy** section and enable either **Static** or **PAC** option to configure proxy settings for the Enterprise Agent:

![](/files/-M62_WepERCT-ANOJ8jd)

### Configuring Proxy Settings for APT Package Manager

A separate proxy configuration for APT (Ubuntu's package manager) is available below the **Web Proxy** section. Scroll down to **Apt Proxy** section, and check the **Use Apt Proxy** box. If you wish to use the same proxy settings for the APT proxy as for your web proxy, check the **Same as Web Proxy** box. If a proxy for APT is not configured, the APT package manager will attempt to perform automatic package updates directly to the APT repositories, without using a proxy.

![APT proxy configuration section](/files/-M62_Wexx9WElHw4LgRa)

Click **Save** when you have finished configuring settings.

## 4. Configure Proxy Settings on Linux Package-Based Enterprise Agents

Enterprise Agents deployed with the Linux package can be [configured during installation](https://docs.thousandeyes.com/product-documentation/enterprise-agents/installing-enterprise-agents-in-proxy-environments) to use a proxy. The install\_thousandeyes.sh installation script provides command line flags to specify proxy information, and will use that information to configure the /etc/te-agent.cfg file. Users can later modify this file using an editor and restart the Agent to make configuration changes.

### Configure Proxy Settings for Enterprise Agent Software

The following proxy configuration settings are available in **/etc/te-agent.cfg** configuration file:

* **proxy-type:** Possible values are DIRECT, STATIC or PAC.
  * DIRECT is when you connect directly to the internet and do not use a proxy.
  * STATIC is when you set the proxy configuration directly on the agent.
  * PAC is when you use a PAC file download to configure the proxy.
* **proxy-location:** The means for obtaining the proxy hostname (or IP address) and port number:
  * When **proxy-type** is set to "STATIC", the **proxy-location** setting should contain \<PROXY-HOSTNAME:PROXY-PORT>
  * When **proxy-type** is set to "PAC", the **proxy-location** setting should contain a URL to the location of the proxy PAC file:
    * "file:///absolute/path/to/my/proxy.pac for a PAC file installed on the local file system, or
    * "<http://my.domain.com/proxy.pac>" for a PAC file that is loaded from a remote web server
  * When **proxy-type** is set to "DIRECT", the **proxy-location** setting is ignored and no proxy is used by the agent.
* **proxy-bypass-list:** Applies only when **proxy-type** is set to STATIC. An unquoted list of domain names, IP addresses or networks to which each request will be compared. Matching requests are sent directly, rather than sent through a proxy. Multiple entries are separated by semi-colons (no whitespace). The \* wildcard is permitted with trailing domain name expressions. For example, \*.example.com would match [www.example.com](http://www.example.com) and [www.us.example.com](http://www.us.example.com). Networks can be specified by CIDR notation, such as 192.168.1.0/24. DNS resolution is not performed in order to check request IP addresses against addresses or networks in the bypass list.
* **proxy-auth-type** - Authentication protocol supported by the proxy server. Can either be empty (when no proxy authentication is required), `BASIC`, `KERBEROS`, or `NTLM`.
* **proxy-user** - Username for proxy authentication
* **proxy-pass** - Password for proxy authentication
* **proxy-host** - OBSOLETE. Use **proxy-location** setting.
* **proxy-port** - OBSOLETE. Use **proxy-location** setting.

{% hint style="info" %}
Kerberos authentication must be configured in [**Network & App Synthetics > Agent Settings > Enterprise Agents > Kerberos Settings**](https://docs.thousandeyes.com/product-documentation/global-vantage-points/working-with-agent-settings#kerberos-settings) before it can be implemented.
{% endhint %}

{% hint style="info" %}
When **proxy-type** is set to PAC, the PAC file is loaded from the URL provided when the Enterprise Agent container is started. If the PAC file is updated, container restart is required for the new PAC file to be loaded again.
{% endhint %}

### Examples

The following examples show various proxy configurations specified in an **/etc/te-agent.cfg** file.

Static proxy configuration example:

```
### Statc proxy configuration
#
# When configuring "STATIC" proxy configuration, configuration
# directive "proxy-location" accepts either an IP address or
# a domain name followed by a colon and a TCP port number.
#
proxy-type=STATIC
proxy-location=10.1.2.32:3128


### Proxy server authentication
#
# If your proxy server requires authentication, the following four
# configuration directives provide the details.
#
# Proxy auth type can be one of:
# - "" (empty, without quotes - when proxy authentication is not required)
# - BASIC
# - KERBEROS
# - NTLM
#
proxy-auth-type=BASIC
proxy-user=jsmith@example.com
proxy-pass=pr0Xyp@ss


### Bypassing proxy for certain test targets
#
# If certain test targets should be excluded from using the proxy,
# "proxy-bypass-list" can be used to match against requests with
# those targets. Unquoted, semicolon-separated list without
# whitespace.
#
proxy-bypass-list=*example.com;localhost;127.0.0.1;192.168.1.0/24
```

PAC-based proxy configuration example:

```
### PAC file proxy configuration
#
# When configuring "PAC" proxy configuration, configuration
# directive "proxy-location" accepts one of the following:
# "file:///..." for PAC file accessible on the agent's filesystem.
# "http://..." for .pac file which is downloaded from remote HTTP server.
#
# If using "file:///..." option, note the use of triple forward slash.
#
proxy-type=PAC
proxy-location=file:///absolute/path/to/my/proxy.pac
#proxy-location=http://my.domain.com/my/proxy.pac


### Proxy server authentication with PAC file
#
# PAC files do not supply proxy server user credentials.
#
# If your proxy server requires authentication, the following four
# configuration directives provide the details.
#
# Proxy auth type can be one of:
# - "" (empty, without quotes - when proxy authentication is not required)
# - BASIC
# - KERBEROS
# - NTLM
#
proxy-auth-type=BASIC
proxy-user=jsmith@example.com
proxy-pass=pr0Xyp@ss


### Bypassing proxy for certain test targets with PAC file
#
# NOTICE: When "PAC" proxy configuration is used, "proxy-bypass-list"
# configuration directive is ignored.
#
# Proxy bypass exceptions must be defined in the PAC file itself.
#
#proxy-bypass-list=
```

Once done editing **/etc/te-agent.cfg**, restart the **te-agent** service to pick up the updated configuration:

```
sudo systemctl restart te-agent
```

### Configuring Proxy Settings for the APT Package Manager on Ubuntu

Ubuntu's [APT](https://en.wikipedia.org/wiki/Advanced_Packaging_Tool) package manager must be configured separately from the Agent's proxy configuration. The proxy used by the package manager need not be the same proxy used for the main Agent processes. Alternatively, if all needed repositories are mirrored on the internal network, or if communication to standard repositories on the Internet is permitted without a proxy, you can skip this step.

**NOTE:** Proxy configuration using a PAC file is not supported by the [APT](https://en.wikipedia.org/wiki/Advanced_Packaging_Tool) package manager. Static APT proxy configuration must be used instead.

To configure a proxy for the APT package manager, create a text configuration file within the /etc/apt/apt.conf.d directory. In this example, we will create the /etc/apt/apt.conf.d/90proxyapt file to store APT proxy configuration. Use an editor to insert the following content into the /etc/apt/apt.conf.d/90proxyapt file:

```
Acquire::http::proxy  "http://<APT_PROXY_USERNAME:APT_PROXY_PASSWORD@>APT_PROXY_HOSTNAME:APT_PROXY_PORT";
Acquire::https::proxy "http://<APT_PROXY_USERNAME:APT_PROXY_PASSWORD@>APT_PROXY_HOSTNAME:APT_PROXY_PORT";
```

An IP address may be used in place of a hostname/domain name. Username and password are optional. Double quotes are required.

Verification of configured proxy can be done using the following command:

```
sudo apt-get update
```

If the command completes successfully, the package manager is configured properly.

### Configuring Proxy Settings for the YUM Package Manager on RHEL / CentOS / Oracle Linux

Red Hat's [YUM](https://en.wikipedia.org/wiki/Yellowdog_Updater,_Modified) package manager must be configured separately from the Agent's proxy configuration. The proxy used by the package manager need not be the same proxy used for the main Agent processes. Alternatively, if all needed repositories are mirrored on the internal network, or if communication to standard repositories on the Internet is permitted without a proxy, then this step can be skipped.

PAC proxy configuration is not supported by the [YUM](https://en.wikipedia.org/wiki/Yellowdog_Updater,_Modified) package manager. Static YUM proxy configuration must be used instead.

YUM package manager configuration is stored in the **/etc/yum.conf** file. Edit the file using an editor and insert the following content into the file:

```
proxy=http://<YUM_PROXY_HOSTNAME>:<YUM_PROXY_PORT>
proxy_username=<YUM_PROXY_USERNAME>
proxy_password=<YUM_PROXY_PASSWORD>
```

Verification of configured proxy settings can be done using the following command:

```
sudo yum makecache
```

If the command completes successfully, the package manager is configured properly.

## 5. Installing Proxy CA Certificates

If your proxy server performs SSL/TLS decryption by re-writing and re-signing server SSL certificates for each server contacted, consult [Installing CA Certificates on Enterprise Agents](https://docs.thousandeyes.com/product-documentation/enterprise-agents/installing-ca-certificates-on-enterprise-agents) and perform the configuration for your Enterprise Agent deployment type (Appliance, Docker container or Linux package).

## 6. Verification

To verify that any Enterprise Agent is successfully communicating through the proxy with the ThousandEyes data collector, check the Enterprise Agent's log file using the following command:

```
tail -f /var/log/te-agent.log
```

Look for entries similar to the following:

```
[te] {} Resolving proxy hostname <proxy hostname or IP address>
[te] {} Calling check in
[te] {} Done calling check in
```

The presence of `Done calling check in` lines indicates that the Enterprise Agent is successfully communicating with the ThousandEyes collector, and the `Resolving proxy hostname` line indicates that the communication is via the proxy. Use `control-c` to exit the `tail` command.


# Writing and Testing Proxy Auto-Configuration (PAC) Files

Similar to web browsers, ThousandEyes Enterprise Agents can use a proxy auto-config (PAC) file to select a proxy server based on the requested URL and other variables. A PAC file contains a single JavaScript function named FindProxyForURL, which will return an object containing one or more proxies, or indicate that the client should not use a proxy and instead connect directly to the web server. Each request by a Web Layer test (HTTP Server, Page Load, Transaction and FTP Server) will be parsed by the PAC file to select a proxy or direct access for that request.

This article discusses creation of PAC files for various use cases. If the PAC file has many lines or complex logic, the `pactester` utility can be used to check the syntax of PAC file.

## PAC File Composition

A PAC file is a text file defining a single JavaScript function: FindProxyForURL(url, host). The FindProxyForURL function is run in a restricted JavaScript environment, with only a limited set of standard JavaScript functions available to define FindProxyForURL. A list of supported functions can be found [here](http://findproxyforurl.com/pac-functions/).

{% hint style="info" %}
ThousandEyes does not recommend the use of the `myIpAddress` function. This condition returns the IP address of the host machine. However, there is no standardized implementation of the function, and this could result in different behavior between the agent and Browserbot.
{% endhint %}

{% hint style="warning" %}
PAC files are cached for a limited time, and reloaded on a five minute interval.

If the PAC file is updated with invalid content, the Enterprise Agent may fail (even if it was previously working). In this case, the agent will continue to fail until the PAC file error is corrected and the agent reloads the valid file.
{% endhint %}

**FindProxyForUrl arguments**

* **url:** The URL of the request, in the form protocol://hostname:port/path. The hostname can be a domain name or IP address. The port number is optional if the default port is used for the given protocol (e.g port 80 for http URLs or port 443 for https URLs).

  Example: <https://www.example.com:8443/mypage.htm>
* **host:** The hostname extracted from the URL string.

  Example: For the URL in the example above, the host would be "[www.example.com](http://www.example.com)"

The url and host variables are populated by the calling program (in the case of an Enterprise Agent, a process that runs a test, uploads data, performs package upgrades, or other functions) and are available for use within the definition of FindProxyForURL.

**FindProxyForUrl return values**

The return value of the FindProxyForUrl function is the value specified by the JavaScript return function inside the FindProxyForUrl function. The value must be comprised of one or more of the following strings:

| Return value (string)   | Result                                                                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| DIRECT                  | Request in the **url** variable will be sent directly to the web server in the **host** variable (see **FindProxyForUrl arguments** above). |
| PROXY **host**:**port** | Request in the **url** variable will use proxy **host** on port number **port**.                                                            |

Specifying more than one string as a return value provides a fallback mechanism. For example, in the following return statement:

```
return "PROXY proxy1.example.com; PROXY proxy2.example.com; DIRECT";
```

if "proxy1.example.com" is unresponsive, the next method specified by the subsequent string will be used, in this case proxying through "proxy2.example.com". If that proxy does not respond, the next request method, "DIRECT" is tried. Multiple strings must be separated by semi-colons. The request method keywords "DIRECT", and "PROXY" are case-sensitive (must be upper-case).

**NOTES:**

* Proxy fallback is only supported for Page Load and Transaction tests (BrowserBot). HTTP Server and FTP Server tests, as well as administrative connections from the Agent to the ThousandEyes platform do not support any fallback proxy or proxies in the PAC file.
* ThousandEyes tests do not currently support SOCKS-based proxies.

### PAC File Example - Basic

A typical PAC file contains multiple `if` statements, each with a `return` function within the execution block of the if statement. When the conditions of the if statement are met, the block's return statement is executed and the FindProxyForUrl function terminates. No further evaluation is performed. If the conditions of an if statement are not met, processing continues. The last line of a PAC file is typically a return statement without an enclosing if statement, which acts as a "clean-up" or "catch-all" rule. JavaScript comments are permitted using "//" and "/\*" syntax. A basic example of a PAC file:

```
function FindProxyForURL(url,host)

{

    // Access the internet directly for one site

    if (dnsDomainIs(host, "www.example.com")) {

        return "DIRECT";

    }

    // No proxy for private (RFC 1918) IP addresses (intranet sites)

    if (isInNet(dnsResolve(host), "10.0.0.0", "255.0.0.0") ||

        isInNet(dnsResolve(host), "172.16.0.0", "255.240.0.0") ||

        isInNet(dnsResolve(host), "192.168.0.0", "255.255.0.0")) {

         return "DIRECT";

    }

    // No proxy for localhost

    if (isInNet(dnsResolve(host), "127.0.0.0", "255.0.0.0")) {

        return "DIRECT";

    }

    // Clean-up rule. Everything else uses a proxy. Note semi-colon delimiter between strings.

    return "PROXY proxy1.example.com:8080; PROXY proxy2.example.com:8080; DIRECT";

}
```

This example demonstrates the basic PAC file constructs for accessing web sites directly using a return value string of "DIRECT", and for accessing web sites using one or more proxies by returning a string containing the proxy or proxies. The example tests the value of the "host" parameter passed to the function using two functions, [dnsDomainIs](http://findproxyforurl.com/pac-functions/) and [dnsResolve](http://findproxyforurl.com/pac-functions/), in "if" statements.

This example also demonstrates a clean-up rule which returns three access methods: two proxies and then the direct access. If the first proxy in the list is not available, the second with be tried after the first request times out. If neither of the two proxies is available, the request will be sent directly to the web server.

### PAC File Example - JavaScript Variables and Methods

PAC files can declare and use JavaScript variables. Additionally, methods for the allowed JavaScript functions can be used.

```
function FindProxyForURL(url,host)

{

    // Declare a variable to store the result of DNS resolution

    // Avoids multiple lookups (even from cache) and DNS A records with multiple mappings

    var host_ip = dnsResolve(host);

    // Declare a variable to store the protocol of the request

    // Extract the protocol from the URL using the substring and indexOf methods

    var protocol = url.substring(0, url.indexOf(":") - 1);


    // No proxy for private (RFC 1918) IP addresses (intranet sites)

    // Using host_ip variable simplifies code for easier reading

    if (isInNet(host_ip, "10.0.0.0", "255.0.0.0") ||

        isInNet(host_ip, "172.16.0.0", "255.240.0.0") ||

        isInNet(host_ip, "192.168.0.0", "255.255.0.0")) {

         return "DIRECT";

    }

    // No proxy for localhost

    if (isInNet(host, "127.0.0.0", "255.0.0.0")) {

        return "DIRECT";

    }

    //Choose a proxy based on the URL's protocol

    if (protocol == "ftp" || protocol == "ftps") {

       return "PROXY ftpproxy.example.com:8021";

    } else if (protocol == "https") {

       return "PROXY sslproxy.example.com:8443";

    } else {

       return "PROXY proxy.example.com:8080";

    }

}
```

In this example, we used methods of the allowed JavaScript functions to extract portions of the URL requested, and assigned values to variables which were used to increase the readability and efficiency of the code.

### PAC File Example - Shell Expressions

The shExpMatch function can be used to match the host or url inputs against a [shell regular expression](https://en.wikibooks.org/wiki/Regular_Expressions/Shell_Regular_Expressions). Shell regular expression characters are similar to regular expressions, but have some differences. Be sure to review the syntax of shell expressions if the differences are not familiar.

```
function FindProxyForURL(url,host)

{

   // For HTTPS URLs, choose a proxy based on the URL's protocol

    if (shExpMatch(url, "https://*")) return "PROXY sslproxy.example.com:8443";


    // For HTTP URLs, choose a proxy based on content in the URL's path (file extension)

    if (shExpMatch(url, "http://*/*.jpg")  || 

        shExpMatch(url, "http://*/*.gif")  ||

        shExpMatch(url, "http://*/*.png")) { 

         return "PROXY imgproxy.example.com:8080";

    } else {

         return "PROXY proxy.example.com:8080";

    }
}
```

In this example, the value of url is compared to shell expressions in two if statements. The first looks for https URLs, and the second for image file extensions, in order to choose the proxy to which the request is sent. Shell expressions can match any part of a URL, such as the URL parameters.


# Enterprise Agent Troubleshooting

This section offers suggestions for how to troubleshoot issues you encounter in the ThousandEyes platform. It includes:

* [Troubleshooting Automatic-Update Problems on Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/troubleshooting/troubleshooting-automatic-update-problems-on-enterprise-agents)
* [Troubleshooting Time Synchronization on Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/troubleshooting/troubleshooting-time-synchronization-on-enterprise-agents)
* [Installing CA Certificates on Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/troubleshooting/installing-ca-certificates-on-enterprise-agents)
* [Agent Unable to Trace Path to Destination?](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/troubleshooting/agent-unable-to-trace-path-to-destination)
* [BrowserBot Installation Fails on Red Hat or CentOS in Amazon EC2](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/troubleshooting/browserbot-installation-fails-on-red-hat-or-centos-in-amazon-ec2)
* [What to Do If te-agent Stops Running Due to a VACUUM Error](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/troubleshooting/what-to-do-if-te-agent-stops-running-due-to-a-vacuum-error)
* [CLI Network Troubleshooting Utilities](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/troubleshooting/cli-network-troubleshooting-utilities)


# How to Generate Packet Captures

When a test is reporting loss from a location that is difficult to trace, and doesn't appear on the path visualization associated with a specific node, the ThousandEyes team might request a packet capture in order to attempt to isolate the loss.

Depending on your operating system, there are several options to run a packet capture. On linux distributions the relevant command to start capture is “tcpdump”. On Windows distributions you can run “netsh”. Packet captures can also be run using the network packet analyzer called “Wireshark” which has versions that work on all major platforms. For additional reference the following links are available for these and other options:

* Ubuntu Manpage: <http://manpages.ubuntu.com/manpages/cosmic/man8/tcpdump.8.html>
* Netsh Command Syntax: <https://docs.microsoft.com/en-us/windows-server/networking/technologies/netsh/netsh-contexts>
* Wincap: <https://www.winpcap.org/>
* Wireshark: <https://www.wireshark.org/docs/wsug_html_chunked/ChapterIntroduction.html#ChIntroWhatIs>

Basically what happens, is you bind the capture to a specific interface, and capture packets passing through that interface. The capture is run over a specific duration to get the required data. Typically, the ThousandEyes team will request a capture over a period of approximately 30 minutes, in order to capture all relevant information. Generating a packet capture on UNIX based systems is achieved running the command "**tcpdump**". This document will provide instructions for obtaining packet captures using either tcpdump or Wireshark.

## Determine Which Network Interface to Capture

To start, you need to first identify which ethernet interface is being used to connect the machine to the network. In most cases, this will be eth0, but to check, run ifconfig on the host to identify the correct interface.

```
dave@vm-dave-dev-1:~$ ifconfig
eth0 Link encap:Ethernet HWaddr 08:00:27:69:f3:a6 
 inet addr:192.168.1.12 Bcast:192.168.1.255 Mask:255.255.255.0
 inet6 addr: fe80::a00:27ff:fe69:f3a6/64 Scope:Link
 UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
 RX packets:216561 errors:0 dropped:0 overruns:0 frame:0
 TX packets:44521 errors:0 dropped:0 overruns:0 carrier:0
 collisions:0 txqueuelen:1000 
 RX bytes:127096906 (127.0 MB) TX bytes:3891185 (3.8 MB)

lo Link encap:Local Loopback 
 inet addr:127.0.0.1 Mask:255.0.0.0
 inet6 addr: ::1/128 Scope:Host
 UP LOOPBACK RUNNING MTU:16436 Metric:1
 RX packets:905 errors:0 dropped:0 overruns:0 frame:0
 TX packets:905 errors:0 dropped:0 overruns:0 carrier:0
 collisions:0 txqueuelen:0 
 RX bytes:84115 (84.1 KB) TX bytes:84115 (84.1 KB)
dave@vm-dave-dev-1:~$
```

In this case, I only have one network interface bound, so I'm going to select that interface by appending -i eth0 to the command. This will bind the capture to the eth0 interface, and capture all the traffic requested through that interface.

```
sudo tcpdump -i eth0
```

## Restricting Capture to a Specific Host or Port

If directed by the ThousandEyes team, you may be requested to reduce the amount of data being captured, by targeting a specific port or host in the request. To restrict based on port, simply append port \<portnumber>. To restrict based on host, simply append host \<w\.x.y.z> to the command. These can be done in tandem, if required; the following commands are all syntactically valid.

```
sudo tcpdump -i eth0 host 1.2.3.4
sudo tcpdump -i eth0 host port 80
```

## Writing Output to a File

We also don't want to interpret the information in real time, but rather capture it to a file that can be used by the ThousandEyes team, so we'll write to a file. This is accomplished by appending a -w \<filename> to the commands.

```
sudo tcpdump -i eth0 host 1.2.3.4 -w myfilename
sudo tcpdump -i eth0 port 80 -w myfilename
```

This command will generate a 1000MB file, as soon as the first one reaches limit tcpdump will start writing the second one and the loop continues. This is very helpful if we need to catch some event in packets.

```
sudo tcpdump -n -s0 -C 1000 -W2 -w file.pcap
```

## Running the Capture

Once you have the required commands, simply start the TCP dump with appropriate parameters. Starting a TCP dump must usually be done in the context of the root user. Running as a root user is not recommended, so the command sudo is often used to run in the context of a super user account. Simply prepend sudo to the command to run a tcpdump with superuser permissions.

```
sudo tcpdump -i eth0 -w myfilename
```

The capture will run until cancelled (press ctrl-c to cancel). Once the tcp dump is stopped, the number of packets captured by the request will be shown:

```
dave@vm-dave-dev-1:~$ sudo tcpdump -i eth0 -w mycapturefile
[sudo] password for dave: 
tcpdump: listening on eth0, link-type EN10MB (Ethernet), capture size 65535 bytes
^C
85 packets captured
85 packets received by filter
0 packets dropped by kernel
```

### Compress the Capture

Once the file has been created, it should be compressed for simplicity of transfer. Simplest method of compression is to use gzip, which is bundled with linux distributions. The syntax is gzip -c uncompressedfile > targetfile.gz, which will create a compressed version of the file for email transmission.

```
gzip -c mycapturefile > mycompressedfile.gz
```

Once the compressed file has been created, send it to the ThousandEyes team for analysis by emailing the gzipped version of the file to <support@thousandeyes.com>.

## Running a Packet Capture from Windows Using Wireshark

Since not everyone has a Mac or Linux server to use, you may need to generate a TCP dump using Windows. The easiest and most common approach to this is using Wireshark (using a GUI), documented below.

First, download WireShark. This will install both the WireShark app and winpcap libraries - these are used to bind to a network adapter, and can be used to capture packets. Download WireShark from <http://www.wireshark.org>

Once you've downloaded WireShark, install it and launch. The great thing about Wireshark is that everything is controllable from a single interface. Under the Capture menu, select Options.

![](/files/-M5xtSAIVDYdTxj75r3Y)

Select the interface you wish to capture by checking the appropriate box, choose appropriate name resolution options (defaults are fine), and ensure that the option for 'use pcap-ng format' is unchecked. Once you're ready to start capturing packets, click the Start button.

Once you click the start button, WireShark will begin capturing packets, and display them in real time. This will be a very busy, color-coded interface, which is moving fast.

Once you've captured enough data, click the stop button (also found under Capture > Stop)

If you want to filter your capture to be based on a specific target IP address, click the Capture > Capture Filters option. This is a very rich expression builder; to target a specific host and port combination (similar to the example above) create a filter similar to the following:

```
tcp.dstport == 80 and ip.addr == 1.2.3.4
```

Once you've applied the filter (if applicable), click File > Save and save the capture file. The save will take the applicable filter into account and will exclude any data not displayed in the filter list. The packet capture file will be large, so always remember to compress the file before sending to ThousandEyes support.

## Using SCP to Transfer the Output

Use Secure Copy Protocol (SCP) to transfer the output of the TCP dump from the ThousandEyes agent to your local machine. Run the command from the machine which you are transferring the file to. Specify the file name and location to copy the file to. Thus, you'll need to include the ending space followed by ".":

```
scp thousandeyes@[IP address of remote agent]:/full/file/path/ .
```


# Troubleshooting Automatic-Update Problems on Enterprise Agents

ThousandEyes software is architected to run a version check upon check-in with the ThousandEyes collector. This process will validate the currently installed version of the agent against the expected version in our system. If running a version lower than the expected version, the Agent will download the required packages, and update them.

This process is run during the update:

| Ubuntu                          | Red Hat Enterprise Linux/CentOS |
| ------------------------------- | ------------------------------- |
| apt-get update                  | yum update                      |
| apt-get install te-agent        | yum install te-agent            |
| apt-get install te-browserbot\* | yum install te-browserbot\*     |

\* The `te-browserbot` package is only required for instances running a browserbot installation. This does require additional resources on a Enterprise Agent (minimum 2GB RAM is recommended)

```
GPG error: http://apt.thousandeyes.com lucid Release: the following signatures couldn't be verified because the public key is not available: NO_PUBKEY C99A1F5BE718900
```

When this occurs, a manual download and registration of the ThousandEyes public key is required. This can be done in either one or two steps: the one-step approach is shown below:

```
wget -q http://apt.thousandeyes.com/thousandeyes-apt-key.pub -O- | sudo apt-key add -
```

This will download and register the ThousandEyes public key, which will allow you to re-run the steps above as required in order to update the agent codebase.


# Troubleshooting Time Synchronization on Enterprise Agents

## Problem

When viewing your Enterprise Agent's status on the **Agents > Enterprise Agents** page, you see a time synchronization warning, such as:

Agent System Time: HH:MM UTC (XX minutes behind)

![](/files/-M5xtHWDWPfFwIUb750m)

or

*Unable to determine agent system clock offset*

In order for ThousandEyes Agents to report data to the ThousandEyes data collector, the data must have correct timestamps. If data timestamps are significantly out of sync with the ThousandEyes collector, the data will not be uploaded to the collector and the above error results.

Time synchronization warnings are only displayed once the offset is greater than 60 seconds. However, shorted offsets can still cause issues with tests and alerts.

## Solution

In order for a ThousandEyes Enterprise Agent to keep proper time, the Network Time Protocol (NTP) must be configured on the Enterprise Agent. NTP is the standard way to perform clock synchronization among networked devices. NTP communication occurs between the device configured for NTP and an NTP server providing the clock synchronization. The process for configuring NTP for an Enterprise Agent has three parts:

1. Select NTP servers
2. Configure any needed firewall rules
3. Configure NTP on the Enterprise Agent

### Select NTP Servers

First, select primary and secondary NTP servers to use. Public NTP servers are available. The most commonly used public servers are the [NTP Pool Project](http://www.pool.ntp.org/) servers, which ThousandEyes agents are often configured to use. If you have a limited number of Enterprise Agents, select two of the following servers:

0.pool.ntp.org\
1.pool.ntp.org\
2.pool.ntp.org\
3.pool.ntp.org

These domain names will be used in Step 2 below, as the servers that each Enterprise Agent will contact to obtain time synchronization information.

Alternatively, you may choose NTP servers which are closer geographically to your location, which can help improve NTP performance. This [link](http://support.ntp.org/bin/view/Support/SelectingOffsiteNTPServers) explains how to [search](http://support.ntp.org/bin/view/Servers/WebSearch) for NTP servers. You may search by geographic region, such as "California" or "Canada".

In addition, your Internet service provider (ISP) or hosting provider will often provide NTP servers to its customers. If your Enterprise Agents are located within your corporate/internal network, then contact the technical support for your ISP to obtain NTP server information. If your Enterprise Agent is located at a hosting/colocation facility, contact the technical support for your hosting provider to obtain NTP server information. If available, it is recommended that you use these NTP servers to avoid adding to the load on the public NTP servers.

For sites with a few dozen or more Enterprise Agents, it is recommended that the organization run its own NTP server locally. Consult the documentation for your organization's server operating systems to select a server for the NTP software. This [link](http://www.ubuntugeek.com/network-time-protocol-ntp-server-and-clients-setup-in-ubuntu.html) describes the process of installing and configuring NTP on Ubuntu Linux.

**NOTE: Most Microsoft Windows Active Directory servers are configured by default to provide NTP.**\
If both the AD servers and the Enterprise Agents are located on your internal network, then use the IP addresses of two of your AD servers as NTP servers for step #3. You may be able to skip step #2, firewall configuration. Consult your network administrator.

### Configure Firewall Rules

Second, ensure the correct firewall configuration to allow NTP from the Enterprise Agent to the NTP servers. Review [Firewall Configuration for Enterprise Agents](https://docs.thousandeyes.com/product-documentation/enterprise-agents/firewall-configuration-for-enterprise-agents) for port and protocol details. The destination IP addresses or domain names for any firewall rules will be the NTP servers.

Additionally, if you have created NTP servers on your own network, ensure that your NTP servers can communicate through any firewalls with the NTP servers that provide time synchronization to your servers.

### Configure NTP

Third, enable the Network Time Protocol (NTP) on the Enterprise Agent. Follow the instructions below for the type of Enterprise Agent requiring NTP: the Virtual Appliance or the Linux package.

#### Virtual Appliance

Connect your browser to the web administration interface of the Virtual Appliance ( [http://\<agent-IP>](/product-documentation/global-vantage-points/enterprise-agents/troubleshooting/troubleshooting-time-synchronization-on-enterprise-agents) ), and select the Time tab. Enter the domain names or IP addresses of your primary and secondary NTP servers, then click Save.

#### Linux Package

To enable NTP for a ThousandEyes Linux package, consult the documentation for your Linux distribution. An example for Ubuntu is available [here](http://www.ubuntugeek.com/network-time-protocol-ntp-server-and-clients-setup-in-ubuntu.html). In other Linux distributions the steps will be similar. The steps have been summarized below:

1. Install the NTP package

   ```
   sudo apt-get install ntp
   ```
2. Open the NTP configuration file with a text editor (nano, in this example). Use sudo if required by your security configuration.

   ```
   sudo nano /etc/ntp.conf
   ```

   Add the NTP primary and secondary server domain names or IP addresses near the top

   ```
     server 0.pool.ntp.org
     server 1.pool.ntp.org
   ```
3. Start NTP

   ```
   sudo /etc/init.d/ntp restart
   ```


# Agent Unable to Trace Path to Destination?

In a strange series of circumstances, you can end up with a Enterprise Agent showing 0% loss, without the path visualization showing connectivity to the destination.

## Problem

There is a disconnect between the loss statistics of the Enterprise Agent (showing 0% loss), and the gateway for the Enterprise Agent (showing 100% loss).

## Cause

This occurs specifically when a Enterprise Agent is connected to the internet behind an Apple Airport gateway, running an up to date firmware revision. This happens due to the fact that Apple Airport routers rewrite the IP header on outbound packets to ensure their routability back to the host which generated them. This disrupts the flow of packets from ThousandEyes, which uses the Identifier field to identify packet sequence.

The example below shows the path visualization of a test which is 100% successful. Note the agent is green, and shows 0% loss, and the endpoint (showing 100% loss) is an Apple Airport device (which is the default gateway for the agent), with 100% loss.

![](/files/-M5xtN3mRaiR5PsRLjk2)

## Resolution

We are working on a workaround for these specific circumstances, but for now, any Enterprise Agent which shows as green, and indicates 0% loss, with a route which terminates on the edge (or gateway) which is an Apple Airport device can be ignored as a troubleshooting point. The fact that we are showing 100% loss at the edge is an indicator of this behavior, rather than an indicator of loss.


# BrowserBot Installation Fails on Red Hat or CentOS in Amazon EC2

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

The BrowserBot component of an Enterprise Agent performs Page Load and Transaction tests. For customers of Amazon Web Service's Elastic Computing 2 platform, installing a Linux Package-based Enterprise Agent with the BrowserBot component in an AWS Red Hat or CentOS virtual machine may fail due to a missing package on which the **te-browserbot** package depends. Most commonly, this is due to a disabled repository that contains the dependency package. To install the BrowserBot component, the repository must first be enabled.

## Identifying the Problem

Installation of BrowserBot with a Linux Package-based Enterprise Agent is normally done via the install\_thousandeyes.sh script with the **-b** flag:

```
sudo ./install_thousandeyes.sh -b <account group installation token>
```

The most common way to detect failure to install BrowserBot is during the execution of the install script in a terminal window. A typical installation failure for BrowserBot would appear similar to the following (emphasis added):

```
[ec2-user@ip-10-0-1-48 ~]$ sudo ./install_thousandeyes.sh -b 12345abcde67890fghij12345klmno12

========================== Welcome to ThousandEyes ============================
[ OK ] checking installation privileges
[ OK ] checking architecture (x86_64)
[ OK ] checking operating system (RedHat/CentOS)
[ OK ] checking ThousandEyes (RedHat) installation tools
[ OK ] detecting RedHat flavor (CentOS/6)
[ OK ] checking repository
[ OK ] loading the ThousandEyes public key
[ OK ] installing the ThousandEyes agent
Configuring ThousandEyes
[ OK ] detecting IP address (209.197.221.99)
Selecting log path: The default log path is /var/log. Do you want to change it [y/N]? N
[ OK ] editing configuration file
Installing Add-ons (RedHat)
[ WARNING ] ThousandEyes' BrowserBot (Package required for Page Load and Transaction tests)
(Failed installing ThousandEyes' BrowserBot)
Starting ThousandEyes
[ WARNING ]ThousandEyes' BrowserBot
(Failed starting ThousandEyes' BrowserBot)
Error: Package: te-browserbot-1.10-1.x86_64 (thousandeyes)
Requires: xorg-x11-server-Xvfb
You could try using --skip-broken to work around the problem
You could try running: rpm -Va --nofiles --nodigest
```

In the above example, BrowserBot (package name "te-browserbot") depends on the **xorg-x11-server-Xvfb** package, which was neither present on the system nor could the package be retrieved from a package repository.

Alternatively, you can find a similar error in the installation log file. The install\_thousandeyes.sh script logs to the /tmp directory in a file "install\_thousandeyes\_<*random characters*>.log". The corresponding error in the install log appears as:

```
yum -y -q install te-browserbot
Error: Package: te-browserbot-1.10-1.x86_64 (thousandeyes)
Requires: xorg-x11-server-Xvfb
```

After running the installation script, your new Enterprise Agent will contact the ThousandEyes collector to register itself. Agent information is displayed on the **Network & App Synthetics > Agent Settings** page, on the **Enterprise Agents** tab. The General Info section will display the installation status of BrowserBot:

![](/files/-M5xtPU4qliXiRSWm1-l)

If logs indicate that a package dependency failed to install, list the system's configured package repositories and their status (enabled or disabled) using the `yum repolist all` command:

```
[ec2-user@ip-10-0-1-48 ~]$ sudo yum repolist all

Loaded plugins: amazon-id, rhui-lb, search-disabled-repos
repo id                                                                          repo name                                                                                status
rhui-REGION-client-config-server-7/x86_64                                        Red Hat Update Infrastructure 2.0 Client Configuration Server 7                          enabled:      6
rhui-REGION-rhel-server-debug-extras/7Server/x86_64                              Red Hat Enterprise Linux Server 7 Extra Debug (Debug RPMs)                               disabled
rhui-REGION-rhel-server-debug-optional/7Server/x86_64                            Red Hat Enterprise Linux Server 7 Optional Debug (Debug RPMs)                            disabled
rhui-REGION-rhel-server-debug-rh-common/7Server/x86_64                           Red Hat Enterprise Linux Server 7 RH Common Debug (Debug RPMs)                           disabled
rhui-REGION-rhel-server-debug-rhscl/7Server/x86_64                               Red Hat Enterprise Linux Server 7 RHSCL Debug (Debug RPMs)                               disabled
rhui-REGION-rhel-server-debug-supplementary/7Server/x86_64                       Red Hat Enterprise Linux Server 7 Supplementary Debug (Debug RPMs)                       disabled
rhui-REGION-rhel-server-extras/7Server/x86_64                                    Red Hat Enterprise Linux Server 7 Extra(RPMs)                                            disabled
rhui-REGION-rhel-server-optional/7Server/x86_64                                  Red Hat Enterprise Linux Server 7 Optional (RPMs)                                        disabled
rhui-REGION-rhel-server-releases/7Server/x86_64                                  Red Hat Enterprise Linux Server 7 (RPMs)                                                 enabled: 11,067
rhui-REGION-rhel-server-releases-debug/7Server/x86_64                            Red Hat Enterprise Linux Server 7 Debug (Debug RPMs)                                     disabled
rhui-REGION-rhel-server-releases-source/7Server/x86_64                           Red Hat Enterprise Linux Server 7 (SRPMs)                                                disabled
rhui-REGION-rhel-server-rh-common/7Server/x86_64                                 Red Hat Enterprise Linux Server 7 RH Common (RPMs)                                       enabled:    196
rhui-REGION-rhel-server-rhscl/7Server/x86_64                                     Red Hat Enterprise Linux Server 7 RHSCL (RPMs)                                           disabled
rhui-REGION-rhel-server-source-extras/7Server/x86_64                             Red Hat Enterprise Linux Server 7 Extra (SRPMs)                                          disabled
rhui-REGION-rhel-server-source-optional/7Server/x86_64                           Red Hat Enterprise Linux Server 7 Optional (SRPMs)                                       disabled
rhui-REGION-rhel-server-source-rh-common/7Server/x86_64                          Red Hat Enterprise Linux Server 7 RH Common (SRPMs)                                      disabled
rhui-REGION-rhel-server-source-rhscl/7Server/x86_64                              Red Hat Enterprise Linux Server 7 RHSCL (SRPMs)                                          disabled
rhui-REGION-rhel-server-source-supplementary/7Server/x86_64                      Red Hat Enterprise Linux Server 7 Supplementary (SRPMs)                                  disabled
rhui-REGION-rhel-server-supplementary/7Server/x86_64                             Red Hat Enterprise Linux Server 7 Supplementary (RPMs)                                   disabled
thousandeyes                                                                     ThousandEyes                                                                             enabled:    114
repolist: 11,383
```

Per the 'status' column (user the horizontal scroll bar below the output to scroll right), many of the repositories have a status of "disabled". If most repositories are disabled, it is likely that the dependency package exists in one of the disabled repositories. Copy this output or make note of which repositories are enabled and which are disabled, as you may wish to use this information later in this procedure.

## Solution

If you know which repository contains the dependency package, enable it using the `yum-config-manager` command. For example, the xorg-x11-server-Xvfb package is contained in the rhui-REGION-rhel-server-optional repository, so you can enable the repository with the following:

```
[ec2-user@ip-10-0-1-48 ~]$ sudo yum-config-manager --enable rhui-REGION-rhel-server-optional
```

If the repository is not known, the simplest way solution is first to enable all of your repositories with the `yum-config-manager` command (but first make note of those repositories that are enabled):

```
[ec2-user@ip-10-0-1-48 ~]$ sudo yum-config-manager --enable \*
```

You can verify the the repository or repositories are enabled by repeating the `yum repolist all` . Or just try to reinstall BrowserBot using the install\_thousandeyes.sh script. The script's output should indicate successful installation of BrowserBot, or you can check the install log.

## Cleanup

Once you've completed the BrowserBot installation, if you enabled all your repositories but wish to have enabled only the repository which provided the dependency package and not any of the others you enabled, you can then determine which repository provided the package using the `yum list <`*`packagename`*`>` command:

```
[ec2-user@ip-10-0-1-48 ~]$ sudo yum list xorg-x11-server-Xvfb
Loaded plugins: amazon-id, rhui-lb, search-disabled-repos
Available Packages
xorg-x11-server-Xvfb.x86_64        1.17.2-10.el7                    rhui-REGION-rhel-server-optional
```

The above output shows that the xorg-x11-server-Xvfb package is available in the"rhui-REGION-rhel-server-optional repository.

Next, disable all packages with the following `yum-config-manager` command:

```
sudo yum-config-manager --disable \*
```

Then, using the information you saved from the first `yum repolist all` command, enable the repositories which should be enabled:

```
sudo yum-config-manager --enable rhui-REGION-client-config-server-7 --enable rhui-REGION-rhel-server-releases --enable rhui-REGION-rhel-server-rh-common --enable thousandeyes --enable rhui-REGION-rhel-server-optional
```

Then verify the repository statuses are correct by repeating the `yum repolist all` command.

## Further Troubleshooting

If enabling all system repositories does not resolve the dependency problem, contact Amazon Web Services technical support to determine what repositories are needed and how to add and/or enable the needed repositories in your /etc/yum.repos.d directory.


# What to Do If te-agent Stops Running Due to a VACUUM Error

The ThousandEyes Enterprise Agent stores results of tests in a local database. When the agent checks in with the ThousandEyes collector, the contents of the database are uploaded to the collector, and the database is purged. In certain circumstances, the local copy of the database can become corrupted, due in large part to disk I/O errors associated with the filesystem storing the database. This phenomenon is documented at <https://www.sqlite.org/howtocorrupt.html>.

When database corruption occurs the Agent will stop, and an error message will be seen in /var/log/te-agent.log, similar to the following:

```
2013-02-06 18:30:06.232 INFO  [te] - Agent version 0.12.1 starting.  Setting max core size to ...
2013-02-06 18:30:06.236 FATAL [te] - Unable to set up agent tables: Error executing "VACUUM", err=11. Please contact support@thousandeyes.com for assistance.
2013-02-06 18:30:06.237 ERROR [te] - Error updating agent status: Error preparing query UPDATE agent_status SET time = datetime('now'), status = 'Unable to set up agent tables: Error executing "VACUUM", err=11. Please contact support@thousandeyes.com for assistance.': err=1
```

As a result, the local database will be stopped and the Agent will be unable to operate. The Agent's status will be shown as "Offline" in the Agent Settings page, with a last contacted date of whenever the first VACUUM error occurred.

![](/files/-M5xtNP86f-n3uBM6aqX)

In order to resolve this, follow the instructions below, per the type of Enterprise Agent (Linux package or Virtual Appliance).

## Linux Package

**As root**, stop the te-agent process, then go to the /var/lib/te-agent/ directory and remove the te-agent.sqlite file, then restart the te-agent process:

**Ubuntu 18.04 and 20.04, Red Hat Enterprise Linux 7 and 8, CentOS 7:**

```
systemctl stop te-agent
cd /var/lib/te-agent
rm te-agent.sqlite
systemctl start te-agent
```

Alternative method when package "initscripts" (RHEL 7, CentOS 7) is installed:

```
service te-agent stop
cd /var/lib/te-agent
rm te-agent.sqlite
service te-agent start
```

## Virtual Appliance

Log into the Virtual Appliance web console and click on the Advanced Settings tab. Click the **Clear Result Cache** button and confirm.

## Contacting ThousandEyes Support

If steps described above do not resolve the issue or if the issue keeps reoccurring, please contact ThousandEyes Customer Engineering team using chat or <support@thousandeyes.com> email address.


# Troubleshooting CAF Agents

This article provides troubleshooting assistance for Cisco Application Hosting Framework (CAF) Enterprise Agents.

## Application Health Check for CAF Containers

CAF based Enterprise Agents can use the infrastructure's built-in application health probe to troubleshoot issues that may prevent the agent from connecting with the ThousandEyes platform. The health probe can provide you with insight into the status of the application running within the container.

The health probe is called every 60 seconds and the results are cached by the app-hosting infrastructure. To see the results of the health probe, use the `show app-hosting detail` command. The example below returns a healthy check:

```
#sh app-hosting det app ExampleApp | sect health 
Application health information
  Status               : 0
  Last probe error     : 
  Last probe output    : 2025-10-01 18:40:51: Agent checking in
```

The example below indicates a DNS error:

```
#sh app-hosting det app ExampleApp | sect health
Application health information
  Status               : 1
  Last probe error     : 2025-10-01 18:21:51: Error calling createAgent: Curl error: Could not resolve host: example.thousandeyes.com
  Last probe output    :
```

The table below outlines the fields and potential values of the health probe:

| Field             | Description                                                                     | Typical Values / Notes                                                                      |
| ----------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Status            | Numeric health status returned by the probe.                                    | **0** = Healthy / success; non-zero = error detected.                                       |
| Last probe error  | Text description of the last health-check failure, if any.                      | Empty if the last probe succeeded.                                                          |
| Last probe output | Output returned from the application's health probe showing the latest results. | The expected result is "Agent checking in" with the timestamp on when the health probe ran. |

## General Troubleshooting FAQs

**What happens if the primary switch in my HA mode stack fails?**

When a Cat9k switch is deployed in HA mode (stacked), for the first 30 minutes, if the primary switch in the stack fails, and a secondary switch takes over, a new agent will be brought up, and the original agent on the failed switch will go offline. After the first 30 minutes, there will be seamless agent failover that preserves agent identity.

**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 start by reviewing the agent health log to identify any issues that have been detected:

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](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/docker-agent-config-options).


# Redeploying Docker-Based Enterprise Agents for runc Security Fixes

As noted [in the ThousandEyes Changelog](https://docs.thousandeyes.com/whats-new/changelog#id-2025-11-21), some Linux Docker-based Enterprise Agents must be updated to apply a new seccomp security profile that addresses runc fixes.

If you encounter the following error when you upgrade **runc** or **docker**, you must perform the steps outlined in this article.

```
Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: error closing exec fds: get handle to /proc/thread-self/fd: unsafe procfs detected: openat2 fsmount:fscontext:proc/thread-self/fd/: function not implemented: unknown
```

## Redeployment Instructions

To avoid errors in your Docker-based Enterprise Agents, do the following for each agent.

1. Delete any existing **te-seccomp.json** file.

   `rm /var/docker/configs/te-seccomp.json`
2. Next, you'll extract the following values from the currently running Enterprise Agent container:

   * **NAME**
   * **HOST\_VOL\_AGENT\_DIR**

   These are the values you entered when you originally deployed the agent in **Network & App Synthetics > Agent Settings**, in the **Add New Enterprise Agent** dialog.

   To extract these values, do the following:

   1. List the running containers.

      `docker ps`
   2. In the output, find and copy the **containerID** for the Enterprise Agent container.
   3. Get the **NAME** value for that container.

      In the following command, replace **\<container\_id>** with the value you retrieved in the previous step.

      `NAME=$(docker inspect -f '{{ .Name | printf "%s" }}' <container_id> | sed 's|^/||')`
   4. Verify that the above command captured the name correctly.

      `echo $NAME`
   5. Get the **HOST\_VOL\_AGENT\_DIR** value for the container.

      In the following command, replace **\<container\_id>** with the value you retrieved in an earlier step.

      `HOST_VOL_AGENT_DIR=$(docker inspect -f '{{ range .Mounts }}{{ if eq .Destination "/var/lib/te-browserbot" }}{{ .Source }}{{ end }}{{ end }}' <container_id> | awk -F'thousandeyes' '{sub(/\/$/, "", $1); print $1}')`
   6. Verify that the above command captured the host volume agent directory correctly.

      `echo $HOST_VOL_AGENT_DIR`
3. In the ThousandEyes platform UI, go to **Network & App Synthetics > Agent Settings** and select the **Enterprise Agents** tab.
4. Click **Add New Enterprise Agent** and select the **Docker** tab.
5. In the dialog that appears, enter the **NAME** value in the **Name** field and the **HOST\_VOL\_AGENT\_DIR** value in the **Host Vol. Agent Directory** field.

   ![Redeploying your Docker-based Enterprise Agent](/files/u85RgEpDpWGwzPd24JV3)
6. Copy the commands from the **Add New Enterprise Agent** dialog, and run them for the agent container.

   ![Redeployment commands](/files/J7cBTzNlL7CcUiL6FSCn)
7. At the command line, verify that the Enterprise Agent's container is running.

   `docker ps`


# What Is BrowserBot?

{% hint style="warning" %}
Due to recent platform-wide naming, navigation, and URL changes in the product, you may notice some discrepancies between the product and the screenshots displayed in our technical documentation. The instructions and actual pages in the product are still valid and haven’t changed. Please bear with us as we update our screenshots to better match the in-product experience. See the full scope of changes on [Naming and Navigation Menu changes - Summary List](https://docs.thousandeyes.com/whats-new/naming-and-nav-phase-2-changes).
{% endhint %}

ThousandEyes [Virtual Appliances](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-virtual-appliance-installation) are shipped with both the Enterprise Agent and BrowserBot components enabled. When [installing the ThousandEyes Enterprise Agent as a Linux package](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/linux-package-agent-installation) on a [supported operating system](https://docs.thousandeyes.com/product-documentation/enterprise-agents/supported-enterprise-agent-operating-systems), you have the option to install BrowserBot, by passing the `-b` flag to the installation script.

## What Is BrowserBot?

The BrowserBot is a component of the agent code that manages page load and transaction tests. This is accomplished through running an instance of the [Chromium](https://www.chromium.org/) browser.

On the other hand, HTTP Server tests are using a custom version of [cURL library](https://curl.haxx.se/) under the hood and therefore do not need the BrowserBot installed.

## BrowserBot Subnet IP Ranges

BrowserBot reserves selected IP ranges exclusively for its own use. These IP ranges cannot be monitored externally if BrowserBot is enabled:

| Platform                         | Subnet Range                                                                  |
| -------------------------------- | ----------------------------------------------------------------------------- |
| Podman: te-browserbot-dual-stack | <ul><li>10.88.2.0/28 (IPv4)</li><li>fd15:cda9:2fb8:eaf9::/64 (IPv6)</li></ul> |
| Podman: te-browserbot-ipv4       | <ul><li>10.88.2.16/28 (IPv4)</li></ul>                                        |

{% hint style="info" %}
If Browserbot is enabled on an agent, all test types are impacted, not just BrowserBot tests.
{% endhint %}

## Can I Install BrowserBot onto an Existing Enterprise Agent?

Yes. To install the BrowserBot component on an existing Enterprise Agent that does not already have it installed, simply re-run the installation script, including your ThousandEyes Account Group token, and the `-b` flag:

```
sudo ./install_thousandeyes.sh -b {your account group token}
```

This will install the BrowserBot and all required dependencies. The BrowserBot version information will now appear in the Enterprise Agent's **General Info** panel in the **Network & App Synthetics > Agent Settings** page, as per the image below:

![](/files/-M5xtOb77Wt5tb4J6jFZ)

## Additional Hardware Resource Requirements

When you install the BrowserBot package on an agent, it requires additional memory. Consult the [Enterprise Agent hardware requirements](https://docs.thousandeyes.com/product-documentation/enterprise-agents/enterprise-agent-hardware-requirements) for full details.

### Podman Version Compatibility for Linux Distributions

If you are deploying your Enterprise Agent with a Linux distribution, it is important to note that Browserbot is not compatible with Podman v5.0.0 or higher. The table below highlights the compatible Podman versions for different Browserbot versions.

| BrowserBot Version          | Compatible Podman Version |
| --------------------------- | ------------------------- |
| BrowserBot v3.6.0 or higher | Podman v4.9.4             |
| BrowserBot v3.5.0 or lower  | Podman v4.4.4             |

## Which Version of Chromium Is BrowserBot Using?

There are two methods of determining the Chromium version used:

### Method 1 - Inspecting HTTP Headers in Waterfall

Pick any Page Load or Transaction test that has headers collection enabled. Open the results view, select one of the agents, switch to the **Waterfall** tab and click on one of the entries' **Headers** link:

![](/files/-M5xtOb90UIpPydT5niN)

Once there, open the **Request Headers** tab and search for the `user-agent` (or `User-Agent` if HTTP protocol version 1.1 was used) header:

![](/files/-M5xtObBc2ZF4trpt5dx)

Notice the browser version specified in the specified request header.

### Method 2 - Inspecting the Installed Package Version

Once you have connected to the agent's SSH console, a simple command suggests the version of Chromium browser used under the hood. For connecting to the SSH console of appliances, we have guides available for [Windows](https://docs.thousandeyes.com/product-documentation/enterprise-agents/connecting-to-the-thousandeyes-virtual-appliance-using-ssh-windows) and [OS X / Linux](https://docs.thousandeyes.com/product-documentation/enterprise-agents/connecting-to-the-thousandeyes-virtual-appliance-using-ssh-mac-linux) workstation operating systems.

For Ubuntu-based operating systems (including ThousandEyes Virtual Appliances), use the following command:

```
$ dpkg -l | grep te-chromium

ii  te-chromium                   68.0.3440.83-1~bionic             amd64        web browser
```

For RHEL/CentOS/Oracle Linux systems, use the following:

```
$ rpm -qa | grep te-chromium

te-chromium-68.0.3440.83-1~centos7.x86_64
```

The commands above will return the name of the package installed and by naming convention that is the version of the browser installed. In the example above, the browser version is `68.0.3440.83` - the `-1` suffix is not part of the browser version information - it is a package release number.

## Related Information

The following resources provide further information about related subjects:

* [What Is an Enterprise Agent?](https://docs.thousandeyes.com/product-documentation/enterprise-agents/what-is-an-enterprise-agent) describes what a customer-deployable ThousandEyes network vantage point is.
* The [Enterprise Agent Hardware Requirements](https://docs.thousandeyes.com/product-documentation/enterprise-agents/enterprise-agent-hardware-requirements) article contains all information about computing resource requirements for running Enterprise Agents.
* [ThousandEyes Virtual Appliance Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-virtual-appliance-installation) provides a step-by-step guide for deploying ThousandEyes agents as virtual appliances.
* [Linux Package Agent Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/linux-package-agent-installation) deals with Enterprise Agent installations directly onto a supported operating system.


# Enterprise Agent Interface Selection

When a ThousandEyes Enterprise Agent has multiple network interfaces each with a unique IP address, or has a single interface with multiple IP addresses, the Interface Selection feature allows a test to use a specific interface or IP address. The test will use the assigned interface to perform all measurements, and set the source IP address of packets to the desired IP address. By providing test-level control of source IP addresses, Interface Selection allows customers to direct test traffic using policy-based routing or similar mechanisms, such as those found in SD-WAN environments.

{% hint style="info" %}
ThousandEyes supports up to eight interfaces on a device.
{% endhint %}

## Use Cases

Using Interface Selection and multiple tests, a customer can configure a single Enterprise Agent to monitor a given target via multiple paths. A common use case is monitoring a multi-homed site or enterprise. When an organization has more than one connection to the Internet, a single Enterprise Agent can run multiple tests, each assigned to a specific link. Links may be physical, or may be Virtual Private Network (VPN) links.

If SD-WAN technology is employed, a dedicated test and interface/address could be used to identify which path the SD-WAN currently uses. The Path Visualization will display hops specific to a path, whether overlay or underlay. Alerts may be constructed based on the IP addresses of hops in the the path.

## Supported test types

Interface Selection is available for all test types except BrowserBot-based tests (page load, transaction, and API test types) and DNS layer tests. The Agents selectors for these test types will not display any additional interface information on an Enterprise Agent with multiple interfaces. This applies to all views of the test type, i.e. a page load test's HTTP server view and network layer views will not display the Interface Selection.

## Configuration Overview

Depending on the current configuration of the system running your Enterprise Agent, configuring Interface Selection is done in up to three steps if adding additional physical or virtual network interfaces, or up to two steps if adding additional IP addresses to an existing interface:

1. Create the physical or virtual network interface adapter for the system (if using multiple interfaces; skipped if using one interface with multiple addresses)
2. Configure the interface with new IP information
3. Configure a test to use the network interface/IP address

### 1) Interface creation

To support Interface Selection with multiple interfaces, the system running an Enterprise Agent must either have multiple network interfaces already installed or the system must have one or more interfaces added. The process to add interfaces depends on the physical hardware, virtualization technology (if used), and operating system. Review the documentation for your hardware, virtualization technology and operating system to add new interfaces, if needed.

Skip this step if using Interface Selection with a single interface having multiple IP addresses.

### 2) Interface configuration

Interface Selection supports multiple interfaces each with a single IP address, or a single interface with multiple IP addresses. ThousandEyes appliances provide configuration of IP information (IP address, netmask, default gateway, etc...) through the web-based administration. Other Agent installation types (Linux package, Docker) are configured according to the operating system used. Review the documentation for your operating system, and review the instructions for your installation type in the **Agent Configuration** section below.

### 3) Test configuration

Once an Enterprise Agent has multiple interfaces or IP addresses configured, tests can be configured to use a specific interface/address of that Agent. A test's **Agents** selector will display the Enterprise Agent with a triangle expander icon beside the Agent's name. Clicking the checkbox beside the Agent's name will make the radio buttons clickable, allowing selection of an interface/IP address.

### Multiple interfaces

The selector below displays an Enterprise Agent with two network interfaces, eth0 (IP address 10.100.10.108) and eth1 (IP address 10.100.10.73).

![](/files/EZGUNqk6l2qqZTMQnMRi)

### Multiple addresses on a single interface

The selector below displays an Enterprise Agent with one network interface, eth0, with two IP addresses 192.168.1.81 and 192.168.1.112.

![](/files/UdvLUGu6HqVvqHkvwMsN)

The selector will also list a **Default interface selection** radio button, which will be selected by default. The default interface will be one of the interfaces listed below the **Default interface selection** radio button. If the system was originally configured with a single interface, then the default interface is usually the original interface. This option exists for users who may be unfamiliar with the Interface Selection feature, to allow them to select an interface that is likely to be sufficient for their needs.

The default interface is the interface associated with the system's default routing table:

```
$ ip route show
default via 192.168.1.254 dev eth0 onlink
169.254.1.0/24 dev eth0  proto kernel  scope link  src 169.254.1.2
172.21.86.172/30 dev sb_parent  proto kernel  scope link  src 172.21.86.173
192.168.1.0/24 dev eth0  proto kernel  scope link  src 192.168.1.83 
```

The command `ip route show` displays the default interface of eth0/192.168.1.83, as shown in the previous image.

## Agent Configuration

The sections below provide instructions to configure each type of Enterprise Agent installation: appliance (virtual or physical), Linux package, and Docker. Each section contain instructions for both the multiple interfaces and single interface/multiple addresses scenarios. Follow the instructions in the section which applies to your type of Enterprise Agent installation and interface/address scenario.

**NOTE:** An Enterprise Agent can only be configured with multiple interfaces or with a single interface having multiple IP addresses. An Enterprise Agent cannot be configured with both methods.

**NOTE:** Interface Selection is not supported on Enterprise Agent clusters.

**NOTE:** The ThousandEyes appliance is typically the easiest installation type to configure when using Interface Selection. Configuration of Linux package and Docker installation types has limitations, and all configuration of the interfaces and addresses is the responsibility of the customer. ThousandEyes recommends using an appliance installation if Interface Selection is required.

### Appliance

The ThousandEyes virtual appliance and physical appliance are configured through the appliance's web administration interface. Log into the web interface and select the appliance's Network tab to configure any additional interfaces or IP addresses. See the following articles for more information on accessing and navigating the web administration interface:

* [ThousandEyes Virtual Appliance Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-virtual-appliance-installation)
* [ThousandEyes Physical Appliance (TEPA) Installation](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/installing/thousandeyes-physical-appliance-installation)
* [Secure access to ThousandEyes appliances](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/secure-access-to-thousandeyes-appliances)

#### Multiple Interfaces

To configure multiple interfaces, first add a virtual network interface in the hypervisor software used to run the virtual appliance, or add a physical network interface. Consult your hypervisor's documentation for instructions on adding a virtual network interface (virtual appliance) or hardware documentation for instructions on adding a physical network interface (physical appliance).

When the appliance has been configured with an additional interface(s), log in to the appliance's web administration console. The **Network** tab displays the initial configuration field(s) for the additional interface(s) below the default interface.

In the configuration setting, select either **Using DHCP** or **Manually**, then configure the IP settings that appear. Note that **Physical Address** is not a configurable field.

![](/files/-Ma-AgyDepAWDdhQ1zml)

Click **Save** at the bottom of the page to save the configuration.

#### Multiple addresses on a single interface

{% hint style="info" %}
Multiple IPv4 or IPv6 addresses on a single interface are supported on ThousandEyes physical and virtual appliances with one interface. Agents with multiple interfaces are not supported.
{% endhint %}

To configure multiple IP addresses on a single interface:

1. Log in to the appliance's web administration console.
2. Open the **Network** tab.

   ![Web Administration Console Network Tab](/files/zjvpHiJCh5jygJoLVBrj)
3. The **+ Add IP address** and **+ Add IPv6 address** links are displayed below the default interfaces for IPv4 and IPv6 respectively. In this image, the `eth0` interface is available for configuration.
4. Click the appropriate link and configure the IP settings that appear. For each address:
   * **IPv4**: Configure the **Name**, **IP Address**, and **Netmask**.
   * **IPv6**: Configure the **IPv6 Address** and the **Prefix Length**.
5. Once the configuration is complete, scroll to the bottom of the page and click **Save Changes**.

{% hint style="info" %}
The **Name** field for IPv4 addresses requires a string without whitespace that can be used to identify the purpose of the address, and will be displayed in the Agents selector of tests. For example, the string "SD-WAN\_IP" could be used to identify an IP address used in an SD-WAN overlay.
{% endhint %}

### Linux package

For supported versions of Ubuntu, Red Hat Enterprise Linux, CentOS and Oracle Linux, customers will need to perform the configuration tasks needed to create interfaces, and then configure the interfaces either statically or via DHCP. Additionally, creation of a new routing table may be required via the iproute2 package, or similar tool.

#### Multiple interfaces

To configure multiple interfaces, first add a physical network interface, or virtual network interface in the hypervisor software used to run the appliance. Consult your hardware or hypervisor documentation for instructions on adding a network interface.

When the system has been configured with an additional interface(s), consult the documentation for your Linux distribution to add IP configuration manually to the interface, and create a routing table for the interface if needed. Configuring the interface via DHCP is not supported when an interface uses a dedicated routing table.

#### Multiple addresses on a single interface

To configure a single interface with multiple addresses, manually add the IP information to the interface. DHCP is not supported for multiple addresses on a single interface.

An example set of commands is below for configuring eth0.

1. Add the new IP address to the running system

```
ip addr add 10.0.0.1/8 dev eth0 label eth0:1
```

2. Add to `/etc/network/interfaces` to persist across reboots

```
iface eth0:1 inet static
address 10.0.0.1
netmask 255.0.0.0
```

### Docker

For the ThousandEyes Docker image, customers will need to perform the configuration tasks needed to create interfaces when invoking the `docker run` command, and then configure the interfaces either statically or via DHCP. Additionally, creation of a new routing table may be required via the iproute2 package, or similar tool. Consult the Docker documentation for further configuration details.

## Viewing selected interfaces

After configuring the Interface Selection feature, selected IP addresses will be displayed in the Path Visualization view. In other test views and parts of the app, the default interface will be displayed.

### Interface Selection in the Path Visualization view

When a test uses an Agent's non-default interface, the Path Visualization view will display the selected interface used in the Agent's tooltip, under the **Interface Details**. Mouse over an Agent in the Path Visualization to display the tooltip:

![](/files/pnXjT5zZ9AVmOUCWuMSs)

In the image above, the IP address 10.100.10.73 from interface eth1 is used for the test.

### Interface Selection in the Overview

In the Overview, the Table tab will display the default interface, and any public IP address (NAT IP address) associated with the default interface:

![](/files/o1ZNETSZNXND3wlHUxXo)

In the image above, the IP address 10.100.10.108 from interface eth0 is displayed, although the test used eth1 (10.100.10.73).

### Interface Selection in Agent Settings

In other views or areas of the app, the default interface's information will be displayed, such as the Agent's General Information section of the Agent Settings page:

![](/files/HZEKZJ7Mj3va0bJolONe)

In the image above, the IP address 10.100.10.108 from the default interface, eth0, is displayed in the **Private IP Address** field. The default interface is always used to contact ThousandEyes for data upload and configuration downloads. Note that the public IP address (NAT IP address) is the address associated with the connections made to ThousandEyes from 10.100.10.108. The public IP address may be the same for traffic from the eth1 interface (10.100.10.73) to the internet, or the public IP address may be different if more than one NAT IP address is available, such as when a NAT address pool is configured on the NAT device, or if multiple paths to the Internet exist and traverse different NAT devices.

## Troubleshooting

A test may display an error similar to the following:

![](/files/q3lVaLnOH6F1Gup4KI2y)

The message "Cannot use the selected interface" appears in the Error Details column. Some reasons for this error:

1. The test uses Interface Selection with a specific (non-default) interface which becomes unavailable.
2. The test uses Interface Selection with a specific (non-default) IPv4 interface but the test's IPv6 **Policy** setting (on the Advanced Settings tab) is configured with "Force IPv6" or "Prefer IPv6" or "Agent's policy" where the policy is "Force IPv6" or "Prefer IPv6" and the test target is either an IPv6 IP address or a domain name that resolves to an IPv6 address.
3. The test uses Interface Selection with a specific (non-default) IPv6 interface but the test's IPv6 **Policy** setting (on the Advanced Settings tab) is configured with "IPv4 only" or "Agent's policy" where the policy is "IPv4 only" and the test target is either an IPv4 IP address or a domain name that resolves to an IPv4 address.
4. The message “Cannot use the selected interface” can occur in all scenarios, not only those where the user has manually selected a particular interface. You may also see it when an interface is automatically selected by the agent as well. The same troubleshooting steps are relevant for the error no matter how it occurs.




---

[Next Page](/llms-full.txt/1)

