Citrix Hypervisor

Upgrade from an existing version

June 11, 2024

Contributed by:

This article describes how to upgrade Citrix Hypervisor by using XenCenter or the xe CLI. It guides you through upgrading your Citrix Hypervisor servers – both pooled and standalone – automatically (using the XenCenter Rolling Pool Upgrade wizard) and manually.

Important:

There are no supported upgrade paths to Citrix Hypervisor 8.2 Cumulative Update 1. All earlier versions of XenServer and Citrix Hypervisor are out of support. If you attempt to upgrade to Citrix Hypervisor 8.2 Cumulative Update 1 from an out-of-support version you are not supported and do so at your own risk.

This article is provided for reference only.

For out-of-support versions of XenServer and Citrix Hypervisor you cannot upgrade to Citrix Hypervisor 8.2 Cumulative Update 1 directly. Perform a clean installation using the Base Installation ISO. For more information, see Install.

To retain VMs from your previous installation of Citrix Hypervisor or XenServer, when no upgrade path is available, export the VMs and import them into your clean installation of Citrix Hypervisor 8.2 Cumulative Update 1. VMs exported from any supported version of Citrix Hypervisor or XenServer can be imported into Citrix Hypervisor 8.2 Cumulative Update 1. For more information, see Import and export VMs.

If you are a Citrix Hypervisor 8.2 Cumulative Update 1 customer who wants to upgrade to a newer version of XenServer, see Upgrade from Citrix Hypervisor 8.2 Cumulative Update 1 in the XenServer 8 documentation.

Before you start

Review the following information before starting your upgrade. Take the necessary steps to ensure that your upgrade process is successful.

Upgrading Citrix Hypervisor servers, and particularly a pool of Citrix Hypervisor servers, requires careful planning and attention. To avoid losing any existing data, either:
- Map your upgrade path carefully.
- Use the XenCenter Rolling Pool Upgrade wizard, and ensure that you select the option to upgrade when you are stepping through the installer.
Check that the hardware your pool is installed on is compatible with the version of Citrix Hypervisor you are about to upgrade to. For more information, see the Hardware Compatibility List (HCL).
If you are using XenCenter to upgrade your hosts, download and install the latest version of XenCenter from the Citrix Hypervisor download site.

For example, when upgrading to Citrix Hypervisor 8.2, use the latest version of XenCenter issued for Citrix Hypervisor 8.2. Using earlier versions of XenCenter to upgrade to a newer version of Citrix Hypervisor is not supported.
Check that the operating systems of your VMs are supported by the version of Citrix Hypervisor you are about to upgrade to. If your VM operating system is not supported in the target version of Citrix Hypervisor, upgrade your VM operating system to a supported version. For more information, see Guest operating system support.
Paravirtualized (PV) VMs are not supported in Citrix Hypervisor 8.2 Cumulative Update 1. 32-bit PV VMs are blocked from starting on Citrix Hypervisor 8.2 Cumulative Update 1 servers. Ensure that before upgrading you remove any PV VMs from your pool or upgrade your VMs to a supported version of their operating system. For more information, see Upgrade from PV to HVM guests.

Earlier versions of the Citrix License Server virtual appliance run in PV mode. We recommend that you transition to using the Windows-based Citrix License Server as part of upgrading to Citrix Hypervisor 8.2 Cumulative Update 1.
If you have Windows VMs running in your pool that will be migrated as part of your upgrade, take the following steps for each VM:
- Ensure that the latest version of the XenServer VM Tools for Windows is installed
- Take a snapshot of the VM
If you have Linux VMs running in your pool that will be migrated as part of your upgrade, ensure that the latest version of the Citrix VM Tools for Linux is installed.
Boot-from-SAN settings are not inherited during the manual upgrade process. When upgrading using the ISO or PXE process, follow the same instructions as used in the installation process below to ensure that multipathd is correctly configured. For more information, see Boot from SAN.
Quiesced snapshots are no longer supported. If you have existing snapshot schedules that create quiesced snapshots, these snapshot schedules fail after the upgrade. To ensure that snapshots continue to be created, delete the existing schedule and create a new one that creates non-quiesced snapshots before performing the upgrade.
Legacy SSL mode is no longer supported. Disable this mode on all hosts in your pool before attempting to upgrade to the latest version on Citrix Hypervisor. To disable legacy SSL mode, run the following command on your pool master before you begin the upgrade: xe pool-disable-ssl-legacy uuid=<pool_uuid>
The Container Management supplemental pack is no longer supported. After you update or upgrade to the latest version of Citrix Hypervisor, you can no longer use the features of this supplemental pack.
When you upgrade Citrix Hypervisor, previously applied supplemental packs are removed and so they must be reapplied during or after the upgrade.
The vSwitch Controller is no longer supported. Disconnect the vSwitch Controller from your pool before attempting to upgrade to the latest version on Citrix Hypervisor. After the upgrade, the following configuration changes take place:
- Cross-server private networks revert to single-server private networks.
- Any Quality of Service settings made through the DVSC console are no longer applied. Network rate limits are no longer enforced.
- ACL rules are removed. All traffic from VMs is allowed.
- Port mirroring (RSPAN) is disabled.
If, after update or upgrade, you find leftover state about the vSwitch Controller in your pool, clear the state with the following CLI command: xe pool-set-vswitch-controller address=

Rolling pool upgrades

Citrix Hypervisor enables you to perform a rolling pool upgrade. A rolling pool upgrade keeps all the services and resources offered by the pool available while upgrading all of the hosts in a pool. This upgrade method takes only one Citrix Hypervisor server offline at a time. Critical VMs are kept running during the upgrade process by live migrating the VMs to other hosts in the pool.

Note:

The pool must have shared storage to keep your VMs running during a rolling pool upgrade. If your pool does not have shared storage, you must stop your VMs before upgrading because the VMs cannot be live migrated.

Storage live migration is not supported with rolling pool upgrades.

You can perform a rolling pool upgrade using XenCenter or the xe CLI. When using XenCenter, we recommend using the Rolling Pool Upgrade wizard. This wizard organizes the upgrade path automatically and guides you through the upgrade procedure. If you are using the xe CLI, first plan your upgrade path and then live migrate running VMs between Citrix Hypervisor servers as you perform the rolling pool upgrade manually.

The Rolling Pool Upgrade wizard is available for licensed Citrix Hypervisor customers or those customers who have access to Citrix Hypervisor through their Citrix Virtual Apps and Desktops entitlement or Citrix DaaS entitlement. For more information about Citrix Hypervisor licensing, see Licensing. To upgrade, or to get a Citrix Hypervisor license, visit the Citrix website.

Important:

Do not use Rolling Pool Upgrade with Boot from SAN environments. For more information on upgrading boot from SAN environments, see Boot from SAN.

Upgrade Citrix Hypervisor servers by using the XenCenter Rolling Pool Upgrade wizard

The Rolling Pool Upgrade wizard enables you to upgrade Citrix Hypervisor servers, hosts in a pool or standalone hosts, to the current version of Citrix Hypervisor.

The Rolling Pool Upgrade wizard guides you through the upgrade procedure and organizes the upgrade path automatically. For pools, each of the hosts in the pool is upgraded in turn, starting with the pool master. Before starting an upgrade, the wizard conducts a series of prechecks. These prechecks ensure certain pool-wide features, such as high availability are temporarily disabled and that each host in the pool is prepared for upgrade. Only one host is offline at a time. Any running VMs are automatically migrated off each host before the upgrade is installed on that host.

The Rolling Pool Upgrade wizard also allows you to automatically apply the available hotfixes when upgrading to a newer version of Citrix Hypervisor. This enables you to bring your standalone hosts or pools up-to-date with a minimum number of reboots at the end. You must be connected to the Internet during the upgrade process for this feature to work.

You can benefit from the automatic application of hotfixes feature when you use XenCenter issued with Citrix Hypervisor 8.2 Cumulative Update 1 to upgrade from any supported version of Citrix Hypervisor or XenServer.

Note:

Rolling Pool Upgrade using XenCenter is only available for licensed Citrix Hypervisor customers or those customers who have access to Citrix Hypervisor through their Citrix Virtual Apps and Desktops entitlement or Citrix DaaS entitlement.

The wizard can operate in Manual or Automatic mode:

In Manual Mode, you must manually run the Citrix Hypervisor installer on each host in turn and follow the on-screen instructions on the serial console of the host. When the upgrade begins, XenCenter prompts you to insert the XenCenter installation media or specify a network boot server for each host that you upgrade.
In Automatic Mode, the wizard uses network installation files on an HTTP, NFS, or FTP server to upgrade each host in turn. This mode doesn’t require you to insert installation media, manually reboot, or step through the installer on each host. If you perform a rolling pool upgrade in this manner, you must unpack the installation media onto your HTTP, NFS, or FTP server before starting the upgrade.

Note:

If you are using IIS to host the installation media, ensure that double escaping is enabled on IIS before extracting the installation ISO on it.

Before you upgrade

Before you begin your upgrade, be sure to make the following preparations:

Download and install the latest version of XenCenter provided for Citrix Hypervisor 8.2 Cumulative Update 1 from the Citrix Hypervisor Product Download page. Using earlier versions of XenCenter to upgrade to a newer version of Citrix Hypervisor is not supported.
We strongly recommend that you take a backup of the state of your existing pool using the pool-dump-database xe CLI command. For more information, see Command line interface. Taking a backup state ensures that you can revert a partially complete rolling upgrade to its original state without losing VM data.
Ensure that your hosts are not over-provisioned: check that hosts have sufficient memory to carry out the upgrade.

As a general guideline, if N equals the total number of hosts in a pool, there must be sufficient memory across N-1 hosts to run all of the live VMs in the pool. It is best to suspend any non-critical VMs during the upgrade process.
If you have vGPU-enabled VMs running on your pool, complete the following steps to migrate the pool while these VMs are running:
- Ensure that the GPU you are using is supported on the version you plan to upgrade to.
- Identify a version of the NVIDIA drivers that is available for both your current version of Citrix Hypervisor and the version of Citrix Hypervisor you are upgrading. If possible, choose the latest available drivers.
- Install the new NVIDIA drivers on your Citrix Hypervisor servers and the matching guest drivers on any of your vGPU-enabled VMs.
- Ensure that you also have the version of the NVIDIA driver that matches the version of Citrix Hypervisor that you are upgrading to. You are prompted to install these drivers as a supplemental pack as part of the Rolling Pool Upgrade process.

Rolling Pool Upgrade wizard checks that the following actions have been taken. Perform these actions before you begin the upgrade process:

Empty the CD/DVD drives of the VMs in the pools.
Disable high availability.

Upgrade process

To upgrade Citrix Hypervisor hosts by using the XenCenter Rolling Pool Upgrade wizard:

Open the Rolling Pool Upgrade wizard: on the Tools menu, select Rolling Pool Upgrade.
Read the Before You Start information, and then click Next to continue.
Select the pools and any individual hosts that you want to upgrade, and then click Next.
Choose one of the following modes:
- Automatic Mode for an automated upgrade from network installation files on an HTTP, NFS, or FTP server
- Manual Mode for a manual upgrade from either a USB/CD/DVD or using network boot (using existing infrastructure)
Notes:

If you choose Automatic Mode and are using IIS to host the installation media, ensure that double escaping is enabled on IIS before extracting the installation ISO on it.

If you choose Manual Mode, you must run the Citrix Hypervisor installer on each host in turn. Follow the on-screen instructions on the serial console of the host. When the upgrade begins, XenCenter prompts you to insert the Citrix Hypervisor installation media or specify a network boot server for each host that you upgrade.
Choose whether you want XenCenter to automatically download and install the minimal set of updates (hotfixes) after upgrading the servers to a newer version. The apply updates option is selected by default. However, you must have an internet connection to download and install the updates.
After you have selected your Upgrade Mode, click Run Prechecks.
Follow the recommendations to resolve any upgrade prechecks that have failed. If you want XenCenter to resolve all failed prechecks automatically, click Resolve All.

When all prechecks have been resolved, click Next to continue.
Prepare the Citrix Hypervisor installation media.

If you chose Automatic Mode, enter the installation media details. Choose HTTP, NFS, or FTP and then specify the URL, user name, and password, as appropriate.
Notes:
- If you choose FTP, ensure that you escape any leading slashes that are in the file path section of the URL.
- Enter the user name and password associated with your HTTP or FTP server, if you have configured security credentials. Do not enter the user name and password associated with your Citrix Hypervisor pool.
- Citrix Hypervisor supports FTP in passive mode only.
If you chose Manual Mode, note the upgrade plan and instructions.

Click Start Upgrade.
When the upgrade begins, the Rolling Pool Upgrade wizard guides you through any actions you must take to upgrade each host. Follow the instructions until you have upgraded and updated all hosts in the pools.

If you have vGPU-enabled VMs, when you reach the step that gives you the option to supply a supplemental pack, upload the NVIDIA driver that matches the one on your vGPU-enabled VMs. Ensure you upload the version of the driver for the Citrix Hypervisor version you are upgrading to.

Note:

If the upgrade or the update process fails for any reason, the Rolling Pool Upgrade wizard halts the process. This allows you to fix the issue and resume the upgrade or update process by clicking the Retry button.
The Rolling Pool Upgrade wizard prints a summary when the upgrade is complete. Click Finish to close the wizard.

Notes:

After a Rolling Pool Upgrade is complete, a VM might not be located on its home server. To relocate the VM, you can do one of the following actions:

Live migrate the VM to its home server

Shut down the VM and then start it on its home server

Upgrade Citrix Hypervisor servers by using the xe CLI

Performing a rolling pool upgrade using the xe CLI requires careful planning. Be sure to read the following section with care before you begin.

Plan an upgrade path

As you plan your upgrade, it is important to be aware of the following:

You can only migrate VMs from Citrix Hypervisor servers running an older version of Citrix Hypervisor to one running the same version or higher. For example, from version 7.0 to version 7.1 Cumulative Update 2 or from version 7.1 Cumulative Update 2 to version 8.2 Cumulative Update 1.

You cannot migrate VMs from an upgraded host to one running an older version of Citrix Hypervisor. For example, from version 8.2 Cumulative Update 1 to version 7.1 Cumulative Update 2. Be sure to allow for space on your Citrix Hypervisor servers accordingly.
We strongly advise against running a mixed-mode pool (one with multiple versions of Citrix Hypervisor co-existing) for longer than necessary, as the pool operates in a degraded state during upgrade.
Key control operations are not available during the upgrade. Do not attempt to perform any control operations. Though VMs continue to function as normal, VM actions other than migrate are not available (for example, shut down, copy and export). In particular, it is not safe to perform storage-related operations such as adding, removing, or resizing virtual disks.
Always upgrade the master host first. Do not place the host into maintenance mode using XenCenter before performing the upgrade. If you put the master in maintenance mode, a new master is designated.
After upgrading a host, apply any hotfixes that have been released for the upgraded version of Citrix Hypervisor before migrating VMs onto the host.
We strongly recommend that you take a backup of the state of your existing pool using the pool-dump-database xe CLI command. For more information, see Command Line interface. This allows you to revert a partially complete rolling upgrade back to its original state without losing any VM data. If you have to revert the rolling upgrade for any reason, you might have to shut down VMs. This action is required because it is not possible to migrate a VM from an upgraded Citrix Hypervisor server to a host running an older version of Citrix Hypervisor.

Before you begin your rolling pool upgrade

If you are using XenCenter, upgrade XenCenter to the latest version provided on the Citrix download site. The newer version of XenCenter correctly controls older versions of Citrix Hypervisor servers.
Empty the CD/DVD drives of the VMs in the pool. For details and instructions, see Before Upgrading a Single Citrix Hypervisor server.
Disable high availability.

Perform rolling pool upgrades by using the xe CLI

Start with the pool master. Disable the master by using the host-disable command. This prevents any new VMs from starting on the specified host.
Ensure that no VMs are running on the master. Shut down, suspend or migrate VMs to other hosts in the pool.

To migrate specified VMs to specified hosts, use the vm-migrate command. By using the vm-migrate command, you have full control over the distribution of migrated VMs to other hosts in the pool.

To live migrate all VMs to other hosts in the pool, use the host-evacuate command. By using the host-evacuate command, you leave the distribution of migrated VMs to Citrix Hypervisor.
Shut down the pool master.

Important:

You are unable to contact the pool master until the upgrade of the master is complete. Shutting down the pool master causes the other hosts in the pool to enter emergency mode. Hosts can enter emergency mode when they in a pool whose master has disappeared from the network and cannot be contacted after several attempts. VMs continue to run on hosts in emergency mode, but control operations are not available.
Boot the pool master using the Citrix Hypervisor installation media and method of your choice (such as, USB or network). Follow the Citrix Hypervisor installation procedure until the installer offers you the option to upgrade. Choose to upgrade. For more information, see Install.
Warnings:
- Ensure you select the upgrade option to avoid losing any existing data.
- If anything interrupts the upgrade of the pool master or if the upgrade fails for any reason, do not attempt to proceed with the upgrade. Reboot the pool master and restore to a working version of the master.
When your pool master restarts, the other hosts in the pool leave emergency mode and normal service is restored after a few minutes.
Apply any hotfixes that have been released for the new version of Citrix Hypervisor to the pool master.
On the pool master, start or resume any shutdown or suspended VMs. Migrate any VMs that you want back to the pool master.
Select the next Citrix Hypervisor server in your upgrade path. Disable the host.
Ensure that no VMs are running on the host. Shut down, suspend or migrate VMs to other hosts in the pool.
Shut down the host.
Follow the upgrade procedure for the host, as described for the master in Step 4.

Note:

If the upgrade of a host that is not the master fails or is interrupted, you do not have to revert. Use the host-forget command to forget the host. Reinstall Citrix Hypervisor on the host, and then join it, as a new host, to the pool using the pool-join command.
Apply any hotfixes that have been released for the new version of Citrix Hypervisor to the host.
On the host, start or resume any shutdown or suspended VMs. Migrate any VMs that you want back to the host.
Repeat Steps 6–10 for the rest of the hosts in the pool.

Upgrade a single Citrix Hypervisor server by using the xe CLI

Before you upgrade a single Citrix Hypervisor server

Before upgrading a standalone Citrix Hypervisor server, shut down or suspend any VMs running on that host. It is important to eject and empty CD/DVD drives of any VMs you plan to suspend. If you do not empty the CD/DVD drives, you may not be able to resume the suspended VMs after upgrade.

An empty VM CD/DVD drive means the VM is not attached to an ISO image or a physical CD/DVD mounted through the Citrix Hypervisor server. In addition, you must ensure that the VM is not attached to any physical CD/DVD drive on the Citrix Hypervisor server at all.

To empty the CD/DVD drive of a VM by using the xe CLI:

Identify which VMs do not have empty CD/DVD drives by typing the following:

xe vbd-list type=CD empty=false
<!--NeedCopy-->

This returns a list of all the VM CD/DVD drives that are not empty, for example:

    uuid ( RO) : abae3997-39af-2764-04a1-ffc501d132d9
    vm-uuid ( RO): 340a8b49-866e-b27c-99d1-fb41457344d9
    vm-name-label ( RO): VM02_DemoLinux
    vdi-uuid ( RO): a14b0345-b20a-4027-a233-7cbd1e005ede
    empty ( RO): false
    device ( RO): xvdd

    uuid ( RO) : ec174a21-452f-7fd8-c02b-86370fa0f654
    vm-uuid ( RO): db80f319-016d-0e5f-d8db-3a6565256c71
    vm-name-label ( RO): VM01_DemoLinux
    vdi-uuid ( RO): a14b0345-b20a-4027-a233-7cbd1e005ede
    empty ( RO): false
    device ( RO): xvdd
<!--NeedCopy-->

Note the uuid, which is the first item in the list.

To empty the CD/DVD drives of the VMs listed, type the following:
```
xe vbd-eject uuid=uuid

```

Upgrade a single Citrix Hypervisor server by using the xe CLI

To upgrade a single Citrix Hypervisor server by using the xe CLI:

Disable the Citrix Hypervisor server that you want to upgrade by typing the following:
```
xe host-disable host-selector=host_selector_value

```
When the Citrix Hypervisor server is disabled, VMs cannot be created or started on that host. VMs also cannot be migrated to a disabled host.
Shut down or suspend any VMs running on the host that you want to upgrade by using the xe vm-shutdown or xe vm-suspend commands.
Shut down the host by using the xe host-shutdown command.
Follow the Citrix Hypervisor installation procedure until the installer offers you the option to upgrade. Choose to upgrade. For more information, see Install.

Warning:

Be sure to select the upgrade option to avoid losing any existing data.

You don’t have to configure any settings again during the setup procedure. The upgrade process follows the first-time installation process but several setup steps are bypassed. The existing settings for networking configuration, system time, and so on, are retained.

When your host restarts, normal service is restored after a few minutes.
Apply any hotfixes that have been released for the new version of Citrix Hypervisor.
Restart any shutdown VMs, and resume any suspended VMs.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Upgrade from an existing version

June 11, 2024

Contributed by:

June 11, 2024

Contributed by:

Upgrade from an existing version

Before you start

Rolling pool upgrades

Upgrade Citrix Hypervisor servers by using the XenCenter Rolling Pool Upgrade wizard

Before you upgrade

Upgrade process

Upgrade Citrix Hypervisor servers by using the xe CLI

Plan an upgrade path

Before you begin your rolling pool upgrade

Perform rolling pool upgrades by using the xe CLI

Upgrade a single Citrix Hypervisor server by using the xe CLI

Before you upgrade a single Citrix Hypervisor server

Upgrade a single Citrix Hypervisor server by using the xe CLI

In this article