> For the complete documentation index, see [llms.txt](https://docs.thousandeyes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrade-ubuntu-22.04-jammy-based-thousandeyes-appliances.md).

# Upgrading Ubuntu 22.04 Jammy-Based ThousandEyes Appliances

As described in the ThousandEyes [Enterprise Agent Support Lifecycle](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/enterprise-agent-support-lifecycle), ThousandEyes virtual and physical appliances based on Ubuntu 22.04 LTS (“Jammy”) will reach End of Support on April 30, 2027.

After Ubuntu 22.04 LTS reaches End of Life on June 30, 2027, affected Enterprise Agents will no longer be able to communicate with the ThousandEyes platform. To continue using these appliances, upgrade them to Ubuntu 24.04 LTS (“Noble”) or migrate them to a currently supported operating system.

This article describes the in-place operating system upgrade for Ubuntu 22.04 LTS-based ThousandEyes Virtual Appliances (TEVA) and ThousandEyes Physical Appliances (TEPA).

{% hint style="info" %}
These instructions apply only to Ubuntu 22.04 LTS-based TEVA and TEPA appliances. For information about other Enterprise Agent installation types, see [Upgrading Operating Systems for Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents).
{% endhint %}

{% hint style="info" %}
Enterprise Agent appliances continue to perform tests and communicate with the ThousandEyes platform during most of the upgrade. Testing is briefly interrupted when the appliance reboots.
{% endhint %}

## Prerequisites

Before starting the upgrade, confirm that the appliance meets the following requirements:

* The locked appliance is a TEVA or TEPA running Ubuntu 22.04 LTS.
* At least 4 GB of free disk space is available.
* The appliance has a working internet connection, either direct or through a proxy.
* The appliance can access the required Ubuntu and ThousandEyes APT repositories. For connectivity requirements, see [Firewall Configuration for Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/configuring/firewall-configuration-for-enterprise-agents).
* The appliance software is current, and the package manager has no failed or unconfigured packages.

## Identifying Appliances that Require an Upgrade

In the **Network & App Synthetics > Agent Settings** screen on the **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.
```

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

## Backing Up and Restoring the Configuration

Before starting the upgrade, back up the appliance configuration so that you can recover it if the upgrade cannot be completed. For instructions, see [Backup and Restore Your Enterprise Agent Configuration](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/backup-and-restore-your-enterprise-agent-configuration).

## Upgrading Appliances

### Upgrading a Single Agent

1. In either the **Network & App Synthetics > 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](#tracking-the-upgrade-process) to monitor the upgrade.

### Upgrading Multiple Agents in Bulk

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

1. On the **Network & App Synthetics > 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](#tracking-the-upgrade-process) to monitor the upgrade.

### Upgrading Agents Behind a Proxy

{% hint style="warning" %}
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.
{% endhint %}

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 platform 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](#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](#upgrade-a-single-agent), [Bulk Upgrade for Multiple Agents](https://github.com/thousandeyes/docs/tree/prod/product-documentation/global-vantage-points/enterprise-agents/managing/bulk-upgrade-for-multiple-agents/README.md), or [Upgrade Agents Behind a Proxy](#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:

{% hint style="warning" %}
You can also download the upgrade log to see the current status.
{% endhint %}

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

1. Validation of appliance readiness Checking network access, apt/dpkg locks, disk space, inode availability, appliance type, and boot device.
2. Preparation of the package environment (2–3%) Refreshing apt metadata, installing temporary upgrade tools, configuring GRUB, and disabling agent auto-updates.
3. Updating the current Ubuntu 22.04 installation (3–21%) Configuring pending packages, refreshing base-files, and updating existing packages to the latest 22.04 versions.
4. Preparation of the distribution upgrade (22–27%) Installing update-manager-core, validating ThousandEyes repository access, configuring apt and boot parameters, and checking for a required pre-upgrade reboot.
5. Starting the Ubuntu release upgrade (64%) Running do-release-upgrade to migrate from Ubuntu 22.04/jammy to Ubuntu 24.04/noble.
6. Preparation for the post-upgrade reboot (65–70%) Updating console settings, enabling the continuation service, stopping te-va, saving and disabling getty services, and enabling the console notifier.
7. Rebooting into Ubuntu 24.04 (70%) Marking the transition from stage 1 to stage 2.
8. Refreshing the post-upgrade package environment (71–72%) Restoring the ThousandEyes repository configuration, refreshing apt metadata, and cleaning the package cache.
9. Removing obsolete appliance packages (71%)
10. Updating and repairing packages (87–89%) Upgrading installed packages, removing obsolete packages, and repairing broken dependencies.
11. Restoring the expected appliance package set (90–93%) Reconfiguring te-appliance-sidecar, installing required utilities, restoring the Ubuntu minimal package set, and removing unused packages.
12. Cleaning up upgrade artifacts (94%)
13. Restoring appliance services and console access (96–98%) Restoring agent auto-updates, restarting ThousandEyes services, restoring getty services, removing the upgrade console service, and uninstalling temporary tools.
14. Completing the upgrade (99–100%) Recording final statistics, disabling the upgrade service, removing the upgrade marker, and clearing the status file.

The previous appliance upgrade could take up to one hour. Confirm the expected duration for this upgrade path.

### Completing a Pre-Upgrade Reboot

Some appliances might require a reboot before the operating system upgrade can begin. If the workflow performs a pre-upgrade reboot, wait for the appliance to return to a running state, and then start the upgrade again.

After the upgrade is complete, confirm in the appliance's **General Information** that the operating system is Ubuntu 24.04 LTS.

## 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](#upgrade-agents-behind-a-proxy).
2. If the target agent is not proxied, confirm the agent status is `running`.

### Ubuntu Repository Availability

If an Ubuntu repository is temporarily unavailable, the upgrade might fail and succeed on a later retry. Confirm the expected error message, retry interval, and whether any remediation is required before retrying.

### Appliance Package State

An appliance with failed or unconfigured packages might be unable to start the operating system upgrade. Confirm the supported remediation path. Until that path is validated, contact ThousandEyes Support instead of attempting package-repair commands.

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

{% hint style="info" %}
ThousandEyes recommends downloading the log and correcting the issues that caused the upgrade to fail before retrying the upgrade process.
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

## Getting Help

If you encounter an issue while upgrading an appliance, contact [ThousandEyes Support](https://docs.thousandeyes.com/product-documentation/getting-started/getting-support-from-thousandeyes).

## Related Information

* [Enterprise Agent Support Lifecycle](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/enterprise-agent-support-lifecycle)
* [Upgrading Operating Systems for Enterprise Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/upgrading-enterprise-agents)
* [Backup and Restore Your Enterprise Agent Configuration](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/backup-and-restore-your-enterprise-agent-configuration)
* [Replacing an Enterprise Agent Using the Agent Clustering Method](https://docs.thousandeyes.com/product-documentation/global-vantage-points/enterprise-agents/managing/replacing-an-enterprise-agent-using-the-agent-clustering-method)