Resetting an Enterprise Agent

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.

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. 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.

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 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 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 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:

  1. Browse to https://<Appliance_IP_address> then log in to the web console

  2. Open the Advanced Settings tab

  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:

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.

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 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 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 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 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

These steps are a variant on "Reconfiguring the Docker Container".

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
PreviousConfiguring a Local Mirror of the ThousandEyes Package RepositoryNextWorking with Enterprise Agent Clusters

Last updated