Enterprise Agent Management

The Labels feature has been upgraded to Tags. All your existing labels have been automatically migrated to the new tagging system with no action required on your part. Existing labels were converted to a tag key with an empty value (for example, a label named subnet-10 is now a tag with the key subnet-10 and no value). You can now manage all tags centrally by navigating to Manage > Tags.

ThousandEyes Enterprise Agents can be added, configured, and managed from the Network & App Synthetics > Agent Settings page of the ThousandEyes platform. You can customize agent behavior to meet your needs, set up clusters, configure Kerberos and proxy settings, and update notification rules.

This article assumes the user has the required role and/or permissions to access the various parts of the Agent Settings page. For more information on user roles and permissions, see Role-Based Access Control.

This article provides a short summary of how to navigate the tabs and the configurable settings available.

For Cloud Agents, see Cloud Agents.

For Endpoint Agents, see Manage Endpoint Agent Settings.

Overview

Enterprise Agent Settings screen showing a table of agents filtered by account group, including status, tags, hostnames, and utilization

The Agent Settings page has three main tabs:

• The Enterprise tab includes all Enteprise Agents and clusters within the organization.

• The Cloud tab includes all the Cloud Agents your organization can access. See Cloud Agents.

• The Global configuration tab includes configuration sections for proxies, Kerberos, and notifications.

Enterprise Tab

The Enterprise tab shows all the Enterprise Agents and clusters in your organization, and any relevant information and settings for each agent or cluster. This includes status/last contact, the tags you have assigned the agent, installation type, location, and whether the agent is IPv4 or IPv6 compatible.

You can also add new agents with the + Agent button (see Enterprise Agents for installation instructions).

There are two nested tabs under Enterprise:

• Agents: A table of all individual agents (both online and inactive) that have been configured for the organization. See Agent Settings for more information.

• Clusters: A table of all configured agent clusters in the organization. For more information about agent clusters, see Working Enterprise Agent Clusters.

Each nested tab allows you to sort, filter, and search the table to find the agents or clusters you are looking for. You can add filters with the Add Filter button next to the search bar.

In addition, the Agents nested tab has several additional features:

• The Group By drop-down menu allows you to change the method that your agents are grouped together. Options include installation type, location, and status.

• The Map panel shows where agents are located around the world, and can be expanded (if hidden), or collapsed to allow for more focus on the table.

• The gear icon allows you to change and reorder the columns in the table. Open the modal, select the column checkboxes you want to see, use the grab handle icon to reorder the columns, and then click Save.

• After you select one or more agents, use the Enable and Disable dropdown menus to bulk update the agents or their agent modules (see Agent Modules).

• After you select one or more agents, use the ellipsis dropdown menu to bulk update reverse DNS, notifications, assigned tests, clusters, or account groups.

The controls for bulk updates below the table are available after you select at least one agent.

Global Configuration

The Global Configuration tab allows you to add and configure proxy settings, Kerberos settings and agent notification rules and methods.

There are three nested tabs under Global Configuration:

• Proxy Settings shows a table of the current configured proxies, including name, authentication type, proxy type, and number of agents using it. You can search the table or use the ellipsis icon to duplicate or delete a proxy configuration. To add a new proxy configuration, click the Add New Proxy Configuration button. See Configuring an Enterprise Agent to Use a Proxy Server for more information.

The proxy settings configured under Global Configuration can be applied to Enterprise Agents in the following ways:

• Enterprise Agent > Proxy Configuration > Specific Proxy Configuration: Overrides any proxy configuration defined directly in the Enterprise Agent configuration.

• Enterprise Agent > Network and Security Settings (optional) > Proxy Configuration > Specific Proxy Configuration: Applies the selected proxy configuration through the Network and Security Settings assigned to the Enterprise Agent.

Applying or changing a proxy configuration can affect an Enterprise Agent's ability to connect to the ThousandEyes platform. Use caution when applying these settings, and ensure that the configured proxy allows the required ThousandEyes platform connectivity.

Configuring a proxy on the Agent Settings page makes it an agent-wide setting for all tests. You can configure a per-test proxy for web layer tests in Test Settings.

A per-test proxy setting takes precedence over the agent-wide in-app configuration, which takes precedence over the proxy configured at the agent level.

• Kerberos Settings shows a table of the Kerberos configurations in the organization. You can search for a configuration by name, use the ellipsis icon to duplicate or delete an existing configuration, or click the Add New Kerberos Configuration button to add a new configuration. See Kerberos Settings)for more information.

• Notifications shows a table of the agent notification rules that have been configured in the organization, including the name, conditions, agents assigned the rule, and whether the rule is a "default" rule. You can seach rules by name, use the ellipsis icon to duplicate a notification rule, or click Add New Notification Rule to add a new one. See Agent Notifications for more information.

Agent Settings

You can configure and manage all of your existing Enterprise Agents from the Agents nested tab within Network & App Synthetics > Agent Settings > Enterprise. Use the filters, Group By menu, and search function to identify which agents you want to configure.

You can bulk update one or more agents by selecting the checkbox for each agent and then using the controls below the table:

• Enable: Enable the selected agents or add agent modules to them.

• Disable: Disable the selected agents or remove agent modules from them.

• Manage Tags: Takes you to the Manage > Tags page to configure your account tags.

• Ellipsis: Configure the reverse DNS settings, agent notifications, assigned tests, and clusters of the selected agents, or add them to account groups.

• Delete: Delete the selected agents.

To configure an individual agent's settings, select the agent in the table to open the Agent Setting modal.

Configure Agent Settings

The Agent Settings modal has three nested tabs:

• Basic Configuration

• Advanced Settings

• Agent Statistics

Basic Configuration will not be visible if the agent is assigned to an Enterprise Agent cluster, and other parts of the interface will change or to reflect the agent's membership in the cluster. Information no longer available under the agent will be available under the agent's cluster.

Additionally, the right hand side of the modal shows the assigned tags, cluster, detailed agent information, and some administrative options. See Additional Information.

The sections below provide a summary of the configurable fields. Once you have configured the agent, click Save Changes to save, or Cancel to revert the changes.

Basic Configuration

• *Agent Name: The name of the agent. This can be modified in the ThousandEyes agent settings UI by a user having a role with the Edit agents in account group permission.

• Territory/Country: Obtained from a geolocation service based on the public IP address of the agent. Can be overridden using the pull-down selector.

• Region/City: Obtained from a geolocation service based on the public IP address of the agent. Can be overridden using the pull-down selector.

• Account Groups: Displayed for users having a role with the Edit agents in account group permission and whose organizations contain more than one account group. Shows the account groups to which the Enterprise Agent is assigned and allows agents to be shared across account groups. To share with another account group, expand the pull-down selector and check the box next to the account group.

• Tests: Displays a list of tests to which the agent has been assigned. Users having a role with the Edit tests permission can add or remove tests assigned to this agent.

• Enable agent notifications: Click this checkbox to enable agent Notification Rules to the agent, which will notify users of agent downtime or other agent conditions. The selector below the checkbox is used to assign or edit Notification Rules.

• BrowserBot Package Type: Used for the Dual Chromium option when running browser synthetics tests. This option helps with upgrades to agent software that involve an upgrade to the Chromium browser. See Dual Chromium Option for more information.

  • Dual Chromium Version: Use this option to run specially designated transaction tests on the newer version of Chromium, on this Enterprise Agent.

  • Default: Use this option to run transaction tests using the previous version of Chromium.

Advanced Settings

• IPv6 Policy: Choose a name resolution policy for non browser based tests. Below are the available options:

  • IPv4 Only

  • Prefer IPv6

  • Force IPv6

• Target for Tests IP Address: Used by Network/agent-to-agent and RTP tests to specify the IP address or hostname that the testing agents will use to target this agent. By default, this is the IP address of the agent's network interface. Normally, if the testing agents' packets are traversing the public internet, the Target for Tests field should be set to the IP address shown in the Public IP Address field on the Basic Configuration tab. If the testing agents' packets are traversing a private network, the Target for Tests field should be set to the IP address shown in the Private IP Address field of this Agent Settings screen.

  Valid Target Values: Use a public or private IPv4/IPv6 address or a DNS hostname that resolves for your test agents. Values that are not accepted include some purely internal or non-DNS names (for example, Kubernetes-style names ending in .cluster.local). If the configuration is rejected, use an IP address or a fully qualified hostname that your assigned agents can resolve and reach.

• Behind a NAT: Check this box to enable NAT traversal. Checking this box will allow agents running Network/Agent-to-Agent tests to initiate connections to this Enterprise Agent if it is behind a NAT'ing firewall or similar device without the need for port forwarding rules on the device. For more information on NAT traversal, see NAT Traversal for Agent-to-Agent Tests.

• Proxy Option: Select an appropriate proxy option for scheduled tests. Below are available choices:

  • Direct: Do not use proxy.

  • Enterprise Agent's proxy configuration: Use proxy configured in agent's config file(te-agent.cfg).

  • Specific proxy configuration: Choose from in-app proxy configurations (see the Proxy Settings section in this article).

• Enable Kerberos: Enables Kerberos authentication for agent. Credentials are configured on the Kerberos Settings tab (see the Kerberos Settings section in this article).

• Public IP Ranges: Enterprise Agents perform reverse DNS (rDNS) lookups for private IP ranges by default. To perform rDNS lookups for public IP ranges using your Enterprise Agents, enter the IP ranges in this field.

• Agent Modules: See Agent Modules.

Agent Statistics

• *Agent Uptime: A graph of the agent's connection to the ThousandEyes collector over the past 7 days.

• Agent Utilization: This section charts the agent utilization per test type for the last 24 hours. Data is stored for up to 30 days. Only those test types which the agent is running are displayed. Utilization for a ThousandEyes Enterprise Agent means the amount of time slots in the test queue that are filled by running tests. A high utilization indicates that the agent is barely managing to complete all tests assigned to it, each round.

Additional Information

• Warnings: Displays details of agent conditions requiring user attention.

• Tags: A list of the user-defined and built-in tags to which the agent belongs. Click the down-arrow icon to list the names of the tags or to add the agent to a tag. The Tags box will not be visible if the agent is assigned to a Cluster. To manage tags, navigate to Manage > Tags.

• Cluster/Member of Cluster: Click the Add agent to cluster link to add this Enterprise Agent to an Enterprise Agent Cluster. If the agent is already assigned to a Cluster then the Cluster's name will be displayed. Click the X next to the Cluster name to remove the agent from the Cluster. For more information about adding and removing agent from a cluster, see Working with Enterprise Agent Clusters.

• General Info: Displays the following information:

  • System Information: Click this link to display several categories of information about the system, including the contents of the Agent's config file (te-agent.cfg).

  • Primary Account Group: The name of the account group under which the agent was created (Account Group Token for Installation from the listed group was used to install the agent).

  • Created: The date the agent was installed.

  • Private IP Address: The IP address assigned to the agent system's interface, and to which the agent is bound.

  • Public IP Address: The IP address that the ThousandEyes collector sees during communication with the agent.

  • Operating System: The agent's operating system type and version.

    • Reset Appliance Password: Present only for ThousandEyes Virtual Appliances, and only when they’re connected to the ThousandEyes collector. Click this link to reset the web admin user interface's password back to the default ("welcome"). Console access also can be used to reset the password via a text menu.

  • Agent System Time: Time reported by agent's clock.

  • Agent Version: The version of the ThousandEyes agent software (te-agent package)

  • BrowserBot Version: The version of the BrowserBot software for Page Load and Transaction tests (te-browserbot package)

  • Installation Type: The type of agent installed (for example, Virtual Appliance or Docker container).

  • Image Version: The version of the installation or container image used to deploy the Enterprise Agent. This value applies to image-based installations, such as Docker and Cisco Application Hosting.

  • Appliance Version: The version of the ThousandEyes appliance software running on a Virtual Appliance or Physical Appliance.

Agent Modules

This section of the Agent Settings modal allows you to enable/disable specialized modules for you Enterprise Agent. The available modules are:

• Traffic Insights: This toggle enables Traffic Insights for your agent. See Traffic Insights for more information.

• Credential Vault Accessor: This toggle enables the agent to run tests that use credentials from an external vault, such as the CyberArk® Secrets Manager, Self-Hosted integration. This module is disabled by default and must be enabled for any agent that needs to run the tests using credentials from the external vault. You can enable this module here in the Agent Settings, or when configuring a test. If you select a vault credential during test setup, the platform will prompt you to enable the module on the selected agents. When enabled, the installed module version (e.g., v1.0.2) is displayed next to the toggle. Additionally, once enabled, the Credential Vault Accessor will appear in the list of installed modules in the agent's General Info panel.

Account Group Token

The account group token is an alphanumeric string used to bind an Enterprise Agent to a specific account group, establishing a unique connection with your Enterprise Agent and any specific account groups that a specific account user has on the ThousandEyes platform. To retrieve the account group token via the Agent Settings page:

1. Go to Network & App Synthetics > Agent Settings, open the Enterprise tab, click + Add Agent, select Appliance, and click the eye icon to show the token.

You must have a role with the Edit agents in account group permission to access this page.

The account token is specific to your current account group. All Enterprise Agents installed with this account token will belong to this account group.

Be sure to handle the account token securely, as it can be used to access and consume ThousandEyes resources.

Kerberos Settings

The Kerberos Settings tab lists all the current Kerberos configurations for the organization. Navigate to the Network & App Synthetics > Agents Settings > Enterprise > Global Configuration > Kerberos Settings tab to view the list or add a new configuration.

To set up a new authentication scheme, select Add New Kerberos Configuration. Complete each field, add an associated Enterprise Agent, and select Add. You can also assign an existing configuration to an agent from Agent Details > Kerberos Setting.

The list of domains under the Allow list field indicates which domains are authorized to negotiate with Chromium. This is a required parameter for browser-based tests in order to perform HTTP authentication using kerberos credentials.

Kerberos authentication can be used for any HTTP or BrowserBot test (API, page load, transaction).

Agent Notifications

Enterprise Agent notifications can be generated for three types of events:

• Last Contact: Represents the last contact with the ThousandEyes collector. The default time limit is 30 minutes (agents normally contact the ThousandEyes collector every minute). Notifications can be set to trigger when the value is less than or greater than a defined time limit in minutes.

• Clock Offset: Represents the offset in seconds of the Enterprise Agent's time from true value. The data collected by ThousandEyes requires accurate timestamps. If an Enterprise Agent's clock varies from the ThousandEyes collector's time by a significant fraction of the frequency of any test the agent is running, then the test data can be affected. Most commonly, this condition arises when the agent cannot reach the agent's Network Time Protocol (NTP) servers via the network. Notification rules can be configured to ensure that the agent's clock drift generates a notification.

• Agent Version is Outdated: Triggered when the Agent Version from the Network & App Synthetics > Agents Settings > Enterprise tab indicates the agent's version is less than the current version available. Normally, Enterprise Agents automatically update their agent software, but if conditions prevent update, notification can be generated.

Agent notifications can be received via email or webhook, and via configured integrations, but are not included in the Alerts List menu.

Default Rules

Default notification rules are assigned to all agents added after the rule has been marked as "default". There is no limit to the number of default rules you can have, and you can assign/unassign rules as default whenever you want.

To configure a default rule, navigate to Network & App Synthetics > Agents Settings > Enterprise > Global configuration > Notifications, find the rule in the table either by scrolling or searching, and click the Default checkbox to assign/unassign as needed.

Configure Agent Notification Rules

You can either create a new notification rule by clicking the Add New Notification Rule or click on an existing rule in the table to open the Edit page to configure the rule.

The Edit page has two tabs: Settings and Notifications.

On the Settings tab, configure the appropriate values for the fields below:

• Notification Name: The name of the notification rule. We recommend you define unique names for ease of management, but there is no uniqueness constraint on this field.

• Enterprise Agents: Click the drop-down menu and check the boxes of the Enterprise Agents you want this notification rule assigned to. Agent notifications cannot be assigned to the agent cluster.

• All/Any operator: Set the selector to Any (logical OR) or All (logical AND) which applies to the conditions listed below.

• Conditions: As explained above, Last Contact, Clock Offset or Agent Version is Outdated, along with the appropriate operator and operand, if applicable.

• Add/remove conditions: Click + to add a new condition or - to remove an existing condition. A minimum of one condition is required.

On the Notification tab, configure the emails, webhooks, or integrations you want notifications to be sent with. For more information on configuring notification methods, see Alert Notifications.

Once you've completed the configuration, click Add to create the notification rule, Save Changes to save the edited rule, or Cancel to revert the change.