Replacing an Enterprise Agent Using Agent Identity Files

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.

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)

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. 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 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 and we'll help you out.