Reinstall the Endpoint Agent
To address certain sceanrios that require the agent to be reinstalled, you can leverage the agent reinstallation process and preserve the historical data, alert configurations, labels, tests, and proxies. The reinstallation process also ensures that you do not consume an additional license.
When you initiate the reinstallation, ThousandEyes invokes the agent installation and checks for an existing agent with the same hostname. If an agent is found, the new agent merges with the existing agent and acquires its identity and the hostname. If an agent with the same hostname is not found, a new agent is created that would consume a new license.
Reinstalling a disabled agent will consume a license.

Pre-requisite

To reinstall an agent, you must have the reinstallation key. This key is unique for every account group and ensures only authorized installers are executing the reinstallation process.
To generate the reinstallation key:
  1. 1.
    In the ThousandEyes web application, navigate to Endpoint Agents -> Agent Settings.
  1. 1.
    Click the Regenerate New Key button.
  2. 2.
    The new reinstallation key is displayed. ThousandEyes recommends you save this key locally, as the key cannot be retrieved later. To see a key in plain text, the user needs to regenerate it and revoke any previous keys.
The reinstallation key is unique for every account group and applies to all the users in the account group. This key is permanent (until regenerated) and can be used for all the further reinstallations for the account group.

Reinstalling the Endpoint Agent on Windows

To reinstall the agent on a Windows machine, add the following parameters (with appropriate values) to the installer:
  • ENDPOINT_REINSTALLATION_METHOD
  • ENDPOINT_REINSTALLATION_KEY
For example, msiexec /i \path\to\Endpoint-Agent.msi /qn ENDPOINT_REINSTALLATION_METHOD=MERGE_BY_HOSTNAME ENDPOINT_REINSTALLATION_KEY=<KEY_GOES_HERE>
MERGE_BY_HOSTNAME is the only valid option to trigger the reinstallation flow in the installer.
For reinstallation of agents for Windows via Group Policy, refer the instructions here

Reinstalling the Endpoint Agent on macOS

To reinstall the agent on a macOS machine, add the following parameters (with appropriate values) to the --applyconfig CLI command:
  • reinstallationmethod
  • reinstallationkey
For example, sudo /Applications/ThousandEyes\ Endpoint\ Agent.app/Contents/MacOS/te-agent \ --applyconfig /path/to/epa-installation-config.te-endpoint-agent \ --reinstallationmethod MERGE_BY_HOSTNAME \ --reinstallationkey <KEY_GOES_HERE>
MERGE_BY_HOSTNAME is the only valid option to trigger the reinstallation flow in the installer.

Error Handling

If the reinstallation key or re-installation method is invalid during registration, the system returns a HTTP 200 with a special status indicating that a token was invalid.
Copy link
Outline
Pre-requisite
Reinstalling the Endpoint Agent on Windows
Reinstalling the Endpoint Agent on macOS
Error Handling