Resetting an Enterprise Agent
PreviousConfiguring a Local Mirror of the ThousandEyes Package RepositoryNextWorking with Enterprise Agent Clusters
Last updated
Last updated
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 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.
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. Select the +Add New Agent form. Under the Appliance view, click the Show Account Group Token for Installation link to display the token.
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.
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 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.
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 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 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:
Browse to https://<Appliance_IP_address> then log in to the web console
Open the Advanced Settings tab
Click the Reset Agent State button
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:
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 page for the appropriate account group to confirm that the agent is present.
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 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:
If the agent has been reset and has obtained a new ID, the log will show a line at startup like:
To reset an Enterprise Agent that has been installed on a supported Linux operating system 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:
Stop the agent process by running:
Delete the .sqlite files located in the /var/lib/te-agent/ directory:
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.
Restart the agent process:
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 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:
If the agent has been reset and has obtained a new ID, the log will show a line at startup like:
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:
Stop the container:
Delete the persistent storage directory which was created with the -v option of the docker run command:
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.
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:
If not performing step 3, then restart the container:
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 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:
If the agent has been reset and has obtained a new ID, the log will show a line at startup like:
These steps are a variant on "Reconfiguring the Docker Container".
Stop the application:
De-activate the application:
Modify the Docker options, and exit three times:
Reactivate the application, and confirm that it’s activated:
Start the application, and confirm that it is running:
Connect to the agent's shell
Stop the agent:
Remove the old agent configuration files.
For Cisco Switches:
For Cisco Routers:
Start the agent:
