Upgrade Ubuntu 20.04 Focal-Based ThousandEyes Appliances

As per the ThousandEyes Enterprise Agent Support Lifecycle, ThousandEyes virtual and physical appliances based on the Ubuntu 20.04 (Focal) operating system will reach their End of Support stage at the end of April, 2025.

Unless these appliances are upgraded or otherwise migrated to a currently supported operating system, the ThousandEyes platform will stop accepting data submitted by these Enterprise Agents on June 30th, 2025.

To continue using your appliances, we recommend performing an in-place upgrade. This article provides the steps required to complete that upgrade.

These instructions only apply to Ubuntu 20.04 LTS-based appliances. For information on upgrading other types of Enterprise Agents, see [Upgrading Operating Systems for Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents).

Enterprise Agent appliances will continue to perform tests and communicate with the platform while the upgrade process takes place.

To upgrade your Enterprise Agent locally, follow the proxy environment instructions.

Prerequisites

The following prerequisites need to be met for the appliance to be eligible for the upgrade process:

• Ubuntu 20.04-based physical appliance (TEPA) or virtual appliance (TEVA).

• Minimum 4GB of free disk space.

• Working internet connection (direct or proxied).

• Access to Ubuntu and ThousandEyes APT repositories (connectivity requirements are fully described in Firewall Configuration for Enterprise Agents

Enterprise Agent appliances will continue to perform tests and communicate with the platform while the upgrade process takes place.

The in-place upgrade path will enable the agent auto-update feature on targeted agents, even for agents that have previously had auto-update disabled.

Unlocked appliance agents are not supported.

Identify Appliances that Require an Upgrade

In the Cloud & Enterprise Agents > Agent Settings > Agents tab of the web application, the following notification will be present if there are any agents in your account that are qualified for the upgrade, where "N" is the number of agents:

Operating system upgrades available for N agents.

In the screenshot below, two agents are available for upgrade:

To view the agents that are available for upgrade, either click the View in Table button, or set the Upgrade Available filter to Yes.

Backup and Restore

Prior to the upgrade process, you can backup your agent configuration to prepare for any potential upgrade failure situations. For instructions, see Backup and Restore Enterprise Agent Configuration.

Upgrade Process

Upgrade a Single Agent

To upgrade a single agent using the in-place upgrade method:

1. In either the Cloud & Enterprise Agents > Agent Settings > Agents list view, or the Agent Details view, click the Upgrade Now link under the Agent Status:

   
2. The upgrade workflow panel will launch. Click Start Upgrade after reviewing the notice.

   
3. If the upgrade is initiated successfully, the screen will transition to "Upgrade Started".

   
4. Close the upgrade screen, and review Tracking the Upgrade Process to monitor the upgrade.

Bulk Upgrade for Multiple Agents

To upgrade multiple Enterprise Agents at once using the in-place upgrade method:

1. On the Cloud & Enterprise Agents > Enterprise Agents > Agents page, click the checkbox beside each agent you want to upgrade:

   
2. Open the Edit menu, and select Upgrade Operating System:

   
3. The upgrade workflow panel will launch. Click Start Upgrade after reviewing the notice.

   
4. If the upgrade is initiated successfully, the screen will transition to "Upgrade Started on N Agents", where N is the number of agents.

   
5. Close the upgrade screen, and review Tracking the Upgrade Process to monitor the upgrade.

Upgrade Agents Behind a Proxy

Agents behind a proxy cannot use the in-place upgrade method in the platform (as described in the sections above), because the RPC connections are blocked by the proxy.

1. Connect to the TEVA's UI by navigating to https://<agent_ip or hostname> in a browser.

2. Navigate to the Agent Status page. A yellow warning banner will be visible if an upgrade is available:

   
3. Click Upgrade Now.

4. The console screen will change to the Upgrade Agent Operating System page. Review the page, and click Start Upgrade.

   
5. Return to the ThousandEyes web application to monitor the upgrade status of the agent, as the TEVA UI will not be available for parts of the upgrade process. See Tracking the Upgrade Process for how to monitor the upgrade.

Tracking the Upgrade Process

Once you have completed the steps in Upgrade a Single Agent, Bulk Upgrade for Multiple Agents, or Upgrade Agents Behind a Proxy, the status for the target agent/s will have changed to "Operating system upgrade in progress".

The upgrade progress can be tracked by percentage in the Agent Details panel:

You can also download the upgrade log to see the current status.

As the upgrade progresses, the description for each stage will change. Some stage descriptions include:

• Getting latest package information

• Starting release upgrade

• Reboot pending

• Removing obsolete appliance packages

• Updating packages to latest version

• Enabling all relevant services for te-pa/te-va appliance

• Upgrade complete

The upgrade process can take up to an hour. The agent will continue to perform tests during this process.

The one exception to the agent continuing to perform tests occurs when the agent reboots during the upgrade. The reboot takes approximately one minute.

Depending on the speed of your internet connection, your ISP's quality of connectivity to the relevant APT repository network, and the CPU and I/O speed of your hardware, the upgrade length may differ.

Once the upgrade is completed, the upgrade tracker will disappear. You can confirm the agent OS was successfully upgraded to Ubuntu 20.04 by clicking on the agent and reviewing the General Information section.

Handling Errors

Agent Reachability

After clicking the Start Upgrade button, the ThousandEyes platform checks the reachability of the target agent. If the agent is found to be unreachable, a warning will appear. In this case, follow the troubleshooting steps below:

1. Confirm the target agent is not behind a proxy. If it is proxied, see Upgrade Agents Behind a Proxy.

2. If the target agent is not proxied, confirm the agent status is running.

VM Status and Network Issues

The upgrade process can take up to an hour. During this time, the status of the VM and the network conditions could affect the completion of the upgrade.

The in-place upgrade method prepares a function for the agent to report failures, as well as recover the upgrade process once the agent comes back online. When an upgrade is disrupted, you will see an Upgrade Failed warning in the platform and on the TEVA UI. This warning includes the last step reached and the reason for failure:

The warning banner also includes two links: Retry Upgrade and Download Log. The Retry Upgrade link will restart the upgrade process from where it previously stopped.

ThousandEyes recommends downloading the log and correcting the issues that caused the upgrade to fail before retrying the upgrade process.

While the upgrade process can be restarted, it is possible that it will continue to fail with errors. In this case, the appliance will need to be replaced with a new installation.

Getting Help

If you encounter any issues while upgrading your appliances, contact the ThousandEyes Customer Engineering team for assistance.

Related Information

The following resources contain further information:

• The Enterprise Agent Support Lifecycle Policy explains how ThousandEyes handles Enterprise Agent operating system end-of-life events.

• The Supported Enterprise Agent Operating Systems article lists all currently supported operating systems.