Upgrade a deployment
Important notice about upgrading VDAs
If the Personal vDisk (PvD) component was ever installed on a VDA, that VDA cannot be upgraded to version 1912 LTSR or later. To use the new VDA, you must uninstall the current VDA and then install the new VDA.
This instruction applies even if you never used PvD.
Learn if you’re affected
How PvD might have been installed in earlier versions:
- In the VDA installer’s graphical interface, PvD was an option on the Additional Components page. The 7.15 LTSR and earlier 7.x releases enabled this option by default. So, if you accepted the defaults (or explicitly enabled the option in any release), PvD was installed.
- On the command line, the
/baseimageoption installed PvD. If you specified this option, or used a script that contained this option, PvD was installed.
If you don’t know whether your VDA has PvD installed, run the installer for the new VDA (1912 LTSR or later) on the machine or image.
- If PvD is installed, a message appears, indicating there is an incompatible component.
- For the graphical interface, click Cancel on the page containing the message, and then confirm that you want to close the installer.
- From the CLI, the command simply fails with the displayed message.
- If PvD is not installed, the upgrade proceeds.
What to do
If the VDA does not have PvD installed, follow the usual upgrade procedure.
If the VDA has PvD installed:
- Uninstall the current VDA. For details, see Remove components.
- Install the new VDA.
If you want to continue using PvD on your Windows 7 or Windows 10 (1607 and earlier, without updates) machines, VDA 7.15 LTSR is the latest supported version.
You can upgrade certain deployments to newer versions without having to first set up new machines or sites. That process is also called an in-place upgrade. See Which versions you can upgrade for a list of the versions you can upgrade.
To start an upgrade, you run the installer from the new version to upgrade previously installed core components, VDAs, and certain other components. Then you upgrade the databases and the site.
If you attempt to upgrade a component on an operating system that is not supported for this product version, a message guides you to an article. The information in that article is also available in this article. See Earlier operating systems.
You can upgrade any component that can be installed with the full-product installer, if there is a newer version provided. For other components that are not installed with the full-product installer (such as Citrix Provisioning and Profile Management), see that component’s documentation for guidance. For host upgrades, see the appropriate documentation.
Review all the information in this article before beginning an upgrade.
The following diagram summarizes the upgrade sequence. Details are provided in Upgrade procedure. For example, if you have more than one core component installed on a server, running the installer on that machine upgrades all components that have new versions provided. You might want to upgrade the VDA used in a master image, and then update the image. Then, update the catalog that uses that image and the Delivery Group that uses that catalog. Details also cover how to upgrade the site databases and the site, automatically or manually.
Preliminary site tests
When you upgrade Delivery Controllers and a site, preliminary site tests run before the actual upgrade begins. These tests verify:
- The site database can be reached and has been backed up
- Connections to essential Citrix services are working correctly
- The Citrix License Server address is available
- The configuration logging database can be reached
After the tests run, you can view a report of the results. You can then fix any issues that were detected, and run the tests again. Failure to run the preliminary site tests and then resolve any issues can impact how your site works.
The report containing the test results is an HTML file (
PreliminarySiteTestResult.html) in the same directory as the installation logs. That file is created if it does not exist. If the file exists, its content is overwritten.
Run the tests
- When you’re using the installer’s graphical interface to upgrade, the wizard includes a page where you can start the tests and then display the report. After the tests run and you have viewed the report and resolved any issues that were found, you can rerun the tests. When the tests complete successfully, click Next to continue with the wizard.
- When you’re using the command-line interface to upgrade, the tests run automatically. By default, if a test fails, the upgrade is not performed. After you view the report and resolve issues, rerun the command.
Citrix recommends always running the preliminary site tests and then resolving any issues before you continue the Controller and site upgrade. The potential benefit is well worth the few moments to run the tests. However, you can override this recommended action.
- When upgrading with the graphical interface, you can choose to skip the tests and continue with the upgrade.
- When upgrading from the command line, you cannot skip the tests. By default, a failed site test causes the installer to fail, without performing the upgrade. If you include the /ignore_site_test_failure option, any test failures are ignored and the upgrade proceeds.
When upgrading multiple Controllers
When you start an upgrade on one Controller, and then start an upgrade of another Controller in the same site (before the first upgrade completes):
- If the preliminary site tests have completed on the first Controller, the preliminary site tests page does not appear in the wizard on the other Controller.
- If the tests on the first Controller are ongoing when you start the upgrade on the other Controller, the site tests page appears in the wizard on the other Controller. However, if the tests on the first Controller finish, only the test results from the first Controller are retained.
Test failures not related to the site’s health
- If the preliminary site tests fail due to insufficient memory, make more memory available and then rerun the tests.
- If you have permission to upgrade, but not run site tests, the preliminary site tests fail. To resolve this, rerun the installer with a user account that has permission to run the tests.
The following limitations apply to upgrades:
Selective component install: If you install or upgrade any components to the new version but choose not to upgrade other components (on different machines) that require upgrade, Studio will remind you. For example, let’s say an upgrade includes new versions of the Controller and Studio. You upgrade the Controller but you do not run the installer on the machine where Studio is installed. Studio will not let you continue to manage the site until you upgrade Studio.
You do not have to upgrade VDAs, but Citrix recommends upgrading all VDAs to enable you to use all available features.
- XenApp versions earlier than 7.5: You cannot upgrade from a XenApp version earlier than 7.5. You can migrate from XenApp 6.x; see Migrate XenApp 6.x.
- XenDesktop versions earlier than 7.x: You cannot upgrade from a XenDesktop version earlier than 5.6. To upgrade XenDesktop 5.6 to this release, first upgrade to 7.6 LTSR (with the latest CU), then upgrade to this Citrix Virtual Desktops release.
- XenDesktop Express Edition: You cannot upgrade XenDesktop Express edition. Obtain and install a license for a currently supported edition, and then upgrade.
- Early Release or Technology Preview versions: You cannot upgrade from a Early Release, Technology Preview, or preview version.
- Components on earlier operating systems: You cannot install current VDAs on operating systems that are no longer supported by Microsoft or Citrix. For details, see Earlier operating systems.
- Product selection: When you upgrade from an earlier version, you do not choose or specify the product (Citrix Virtual Apps or Citrix Virtual Desktops) that was set during the initial installation.
- Mixed environments/sites: If you must continue to run earlier version sites and current version sites, see Mixed environment considerations.
- Delivery Controllers earlier than 7.13: When you upgrade a Delivery Controller earlier than 7.13, you may see an error (exception) if the “Auto client reconnect timeout” setting is configured in any policies. This error occurs if the “Auto client reconnect timeout” setting value is outside the permitted range of 0 and 300, which was first introduced in version 7.13. To prevent this error, use the Citrix Group Policy PowerShell Provider to unconfigure the setting, or to set it to a value within the specified range. For an example, see CTX229477.
Before beginning an upgrade, review the following information and complete necessary tasks.
Choose an installer and interface
Use the full-product installer from the product ISO to upgrade components.
You can upgrade VDAs using the full-product installer or one of the standalone VDA installers.
All installers offer graphical and command line interfaces. For more information, see Installers.
You cannot upgrade by importing or migrating data from a version that can be upgraded. Some much earlier versions must be migrated instead of upgraded; see Upgrade and migrate for a list of which versions can be upgraded.
If you originally installed a desktop VDA with the VDAWorkstationCoreSetup.exe installer, Citrix recommends using that installer to upgrade it. If you use the full-product VDA installer or the VDAWorkstationSetup.exe installer to upgrade the VDA, the components that were originally excluded might be installed, unless you expressly omit/exclude them from the upgrade.
For example, let’s say you originally installed a version 7.14 VDA using VDAWorkstationCoreSetup.exe. Later, you use the full-product installer to upgrade that VDA. If you accept the default settings on the full-product installer, the components that were inherently excluded from the original installation (such as Profile Management) might be installed during the upgrade.
When upgrading a VDA to the current release, a machine restart occurs during the upgrade process. (This requirement started with the 7.17 release.) This cannot be avoided. The upgrade resumes automatically after the restart (unless you specify /noresume on the command line).
Check the site health
If a site has issues, upgrading will not fix them. In fact, upgrading can leave the site in a complex state that is difficult to recover from.
When you launch the full-product installer to upgrade a Controller, preliminary site tests run before the actual upgrade begins. After the tests run, you can view a report of the results. If issues were found, you can stop the upgrade and fix the issues. Then, after you resolve the issues, you can begin the upgrade again.
For details, see Preliminary site tests.
Back up the site, monitoring, and configuration logging databases. Follow the instructions in CTX135207. If any issues are discovered after the upgrade, you can restore the backup.
Beginning with XenApp and XenDesktop 7.16, when installing a Delivery Controller, SQL Server Express LocalDB 2014 is installed automatically, for use with Local Host Cache. If you want to upgrade an installed SQL Server Express LocalDB 2014, the new version must be at least SQL Server Express 2017 LocalDB CU16. Do not upgrade to a version earlier than CU16.
Other preparation tasks
- Ensure that your Citrix licensing is up-to-date: Before upgrading, be sure your Customer Success Services / Software Maintenance / Subscription Advantage date is valid for the new product version. If you are upgrading from an earlier 7.x product version, the date must be at least 2019.1115.
Ensure that your Citrix License Server is compatible: Ensure that your Citrix License Server is compatible with the new version. There are two ways to do this:
Before upgrading any other Citrix components, run the XenDesktopServerSetup.exe installer from the ISO layout on the machine containing the controller. If there are any incompatibility issues, the installer reports it with recommended steps to resolve the issues.
From the XenDesktop Setup directory on the installation media, run the command:
.\LicServVerify.exe -h <license-server-fqdn> -p 27000 -v.The resulting display indicates whether the License Server is compatible. If the License Server is incompatible, upgrade the license server following the instructions at Upgrade.
- Close applications and consoles: Before starting an upgrade, close all programs that might potentially cause file locks, including administration consoles and PowerShell sessions. (Restarting the machine ensures that any file locks are cleared, and that there are no Windows updates pending.) Before starting an upgrade, stop and disable any third-party monitoring agent services.
Ensure that you have proper permissions: In addition to being a domain user, you must be a local administrator on the machines where you are upgrading product components.
The Site database and the site can be upgraded automatically or manually. For an automatic database upgrade, the Studio user’s permissions must include the ability to update the SQL Server database schema (for example, the db_securityadmin or db_owner database role). For details, see Databases. If the Studio user does not have those permissions, initiating a manual database upgrade generates scripts. The Studio user runs some of the scripts from Studio. The database administrator runs other scripts, using a tool such as SQL Server Management Studio.
- Back up templates and upgrade hypervisors, if needed.
- Complete any other preparation tasks dictated by your business continuity plan.
Mixed environment considerations
When your environment contains sites/farms with different product versions (for example, a XenDesktop 7.14 site and a Citrix Virtual Desktops 1808 site), Citrix recommends using StoreFront to aggregate applications and desktops from different product versions. For details, see the StoreFront documentation.
- In a mixed environment, continue using the Studio and Director versions for each release, but ensure that different versions are installed on separate machines.
- If you plan to run XenDesktop 5.6 and 7.x sites simultaneously and use Citrix Provisioning (formerly Provisioning Services) for both, either deploy a new Citrix Provisioning for use with the 7.x site, or upgrade to the current Citrix Provisioning and be unable to provision new workloads in the XenDesktop 5.6 site.
Within each site, Citrix recommends upgrading all components. Although you can use earlier versions of some components, all the features in the latest version might not be available. For example, although you can use current VDAs in deployments containing earlier Controller versions, new features in the current release may not be available. VDA registration issues can also occur when using non-current versions.
- If you have a site with Controllers at version 5.x and VDAs at a newer version, complete the upgrade of all components as soon as possible.
- Do not upgrade a standalone Studio version until you are ready to use the new version.
Earlier operating systems
Let’s say you installed an earlier version of a component on a machine that was running a supported operating system (OS) version. Now, you want to use a newer component version, but that OS is no longer valid for the current version of the component.
For example, assume that you installed a 7.14 VDA for Desktop OS on a machine running Windows 7 SP1. Now you want to upgrade that VDA to the current release (let’s say, Citrix Virtual Apps and Desktops 7 1808), but Windows 7 is no longer a valid OS for desktop VDAs.
An invalid OS goes beyond “unsupported.” Unsupported items might be discouraged, but they’re allowed. Invalid means that the Citrix Virtual Apps and Desktops installer does not allow you to install or upgrade the component on the machine running that OS version.
When you try to install or upgrade a component on an operating system that is no longer allowed, an error message displays, such as “Cannot be installed on this operating system”.
The following graphic shows the affected installer components. (Although the picture shows the full-product installer’s graphical interface, invalid operating systems are detected when using the graphical or command-line interface, as well as any of the standalone VDA installers.)
Valid operating systems
Follow the links to learn which OSs are supported for a release.
- Citrix Virtual Apps and Desktops current release (CR):
- Delivery Controller, Studio, Director, VDAs, Universal Print Server
- Federated Authentication Service
- For StoreFront, Self-Service Password Reset, and Session Recording, see the system requirements article for the current release.
- For LTSRs, see the components lists for your LTSR version and CU. (Select your LTSR version from the main Citrix Virtual Apps and Desktops product documentation page.)
Invalid operating systems
The following table lists the earlier operating systems that are not valid for installing/upgrading components in the current release. It indicates the latest valid component version supported for each listed OS, and the component version when installation and upgrade became invalid.
The operating systems in the table include service packs and updates. For example, Windows 7 includes Windows 7 SP1, and Windows 8 includes Windows 8.1. It is assumed that if you’re upgrading, it’s from a 7.x version to a newer version.
|Operating system||Component/feature||Latest valid version||Install/upgrade not possible as of version|
|Windows 7 and Windows 8||VDA||7.15 LTSR||7.16|
|Windows 7 and Windows 8||Other installer components||7.17||7.18|
|Windows 10 versions earlier than 1607||VDA||7.15 LTSR||7.16|
|Windows 10 x86 version||VDA||1906.2.0||1909|
|Windows Server 2008 R2||VDA||7.15 LTSR||7.16|
|Windows Server 2008 R2||Other installer components||7.17||7.18|
|Windows Server 2012||VDA||7.15 LTSR||7.16|
|Windows Server 2012||Other installer components||7.17||7.18|
|Windows Server 2012 R2||Server VDI||7.15 LTSR||7.16|
Windows XP and Windows Vista are not valid for any 7.x components or technologies.
What you can do
You have choices. Review the following options.
Continue with the current OS:
These methods are feasible for VDAs.
If you want to continue using machines with the earlier OS, you can choose one of the following:
- Continue using the installed component version.
- Download the latest valid component version and then upgrade the component to that version. (This assumes that the latest valid component version isn’t already installed.)
For example, let’s say you have a 7.14 VDA on a Windows 7 SP1 machine. The latest valid VDA version on Windows 7 OS machines is XenApp and XenDesktop 7.15 LTSR. You can either continue using 7.14, or download a 7.15 LTSR VDA and then upgrade your VDA to that version. Those earlier VDA versions work in deployments containing Delivery Controllers with newer versions. For example, a 7.15 LTSR VDA can connect to a Citrix Virtual Apps and Desktops 7 1808 Controller.
Reimage or upgrade the machine:
These methods are feasible for VDAs and other machines that do not have core components (such as Delivery Controllers) installed. Choose one of the following:
- After taking the machine out of service (turning on maintenance mode and allowing all sessions to close), you can reimage it to a supported Windows OS version, and then install the latest version of the component.
- To upgrade the OS without reimaging, uninstall the Citrix software before upgrading the OS. Otherwise, the Citrix software will be in an unsupported state. Then, install the new component.
Add new machines with supported operating systems and then remove older machines:
This method is feasible if you must upgrade the OS on machines that contain a Delivery Controller or other core component.
Citrix recommends that all Controllers in a site have the same OS. The following upgrade sequence minimizes the interval when different Controllers have different OSs.
- Take a snapshot of all Delivery Controllers in the site and then back up the site database.
- Install new Delivery Controllers on clean servers with supported operating systems. For example, install a Controller on two Windows Server 2016 machines.
- Add the new Controllers to the site.
- Remove the Controllers that are running on operating systems that are not valid for the current release. For example, remove two Controllers on two Windows Server 2008 R2 machines. Follow the recommendations for removing Controllers in Delivery Controllers.
Most of the examples in this article apply to deployments that use the Current Release (CR) servicing option. The concepts also apply to deployments that use the Long Term Service Release (LTSR) servicing option.
- Between the releases of XenApp and XenDesktop 7.6 LTSR and 7.15 LTSR, no supported OSs became invalid. So, no upgrade issues occurred when moving from the earlier LTSR version to the next.
- In the future (for example, when moving from 7.15 LTSR to the next LTSR version), issues might arise because of OSs identified as invalid during the interval.
Mixed VDA support
When you upgrade the product to a later version, Citrix recommends that you upgrade all the core components and VDAs so that you can access all the new and enhanced features in your edition.
In some environments, you may not be able to upgrade all VDAs to the most current version. In that case, when you create a machine catalog, you can specify the VDA version installed on the machines. By default, this setting specifies the latest recommended VDA version. Consider changing this setting only if the machine catalog contains machines with earlier VDA versions. Mixing VDA versions in a machine catalog is not recommended.
If a catalog is created with the default recommended VDA version setting, and one or more machines has an earlier VDA version, those machines cannot register with the Controller, and will not work.
For more information, see VDA versions and functional levels.
To run the product installer graphical interface, log on to the machine and then insert the media or mount the ISO drive for the new release. Double-click AutoSelect. To use the command-line interface, issue the appropriate command. See Install using the command line.
If more than one core component is installed on the same server (for example, the Controller, Studio, and License Server) and several of them have new versions available, they are all upgraded when you run the installer.
If any core components are installed on machines other than the Controller, run the installer on each of those machines. The recommended order is: License Server, StoreFront, and then Director.
If you have not yet determined whether your License Server is compatible with the new version (see Other preparation tasks), it is essential that you run the installer on the License Server before upgrading any other core components.
If you use Citrix Provisioning, upgrade the Citrix Provisioning servers and target devices. Use the guidance in the Citrix Provisioning documentation.
Run the product installer on machines containing VDAs. (See Step 12 if you use master images and Machine Creation Services.)
Run the product installer on half of the Controllers. (Running the installer also upgrades any other core components installed on those servers.) For example, if your site has four Controllers, run the installer on two of them.
- Leaving half of the Controllers active allows users to access the site. VDAs can register with the remaining Controllers. There may be times when the site has reduced capacity because fewer Controllers are available. The upgrade causes only a brief interruption in establishing new client connections during the final database upgrade steps. The upgraded Controllers cannot process requests until the entire site is upgraded.
- If your site has only one Controller, it is inoperable during the upgrade.
Preliminary site tests run on the first Controller, before the actual upgrade starts. For details, see Preliminary site tests.
If Studio is installed on a different machine than one you’ve already upgraded, run the installer on the machine where Studio is installed.
From the newly upgraded Studio, upgrade the site database. For details, see Upgrade the databases and the site.
From the newly upgraded Studio, select Citrix Studio site-name in the navigation pane. Select the Common Tasks tab. Select Upgrade remaining Delivery Controllers.
After completing the upgrade and confirming completion, close and then reopen Studio. Studio might prompt for an additional site upgrade to register the Controller’s services to the site, or to create a zone ID if it does not exist.
In the Site Configuration section of the Common Tasks page, select Perform registration. Registering the Controllers makes them available to the site.
After you select Finish when the upgrade completes, you are offered the opportunity to enroll in Citrix telemetry programs, which collect information about your deployment. That information is used to improve product quality, reliability, and performance.
After upgrading components, the database, and the site, you can test the newly upgraded site. From Studio, select Citrix Studio site-name in the navigation pane. Select the Common Tasks tab and then select Test Site. These tests run automatically after you upgrade the database, but you can run them again at any time.
The Test Site functionality might fail for a Controller on Windows Server 2016 when a local SQL Server Express is used for the site database, if the SQL Server Browser Service is not started. To avoid this, complete the following tasks.
Enable the SQL Server Browser Service (if required) and then start it.
Restart the SQL Server (SQLEXPRESS) service.
If you use Machine Creation Services and want to use upgraded VDAs: After you upgrade and test the deployment, update the VDA used in the master images (if you haven’t done that already). Update master images that use those VDAs. See Update or create a master image. Then update machine catalogs that use those master images. After updating the catalogs, upgrade Delivery Groups that use those catalogs.
Upgrade the databases and the site
After upgrading the core components and VDAs, use the newly upgraded Studio to initiate an automatic or manual database and site upgrade.
Remember: Check Preparation for permission requirements.
- For an automatic database upgrade, the Studio user’s permissions must include the ability to update the SQL Server database schema.
- For a manual upgrade, the Studio user runs some of the generated scripts from Studio. The database administrator runs other scripts, using either the SQLCMD utility or the SQL Server Management Studio in SQLCMD mode. Otherwise, inaccurate errors can result.
Citrix strongly recommends that you back up the database before upgrading. See CTX135207. During a database upgrade, product services are disabled. During that time, Controllers cannot broker new connections for the site, so plan carefully.
After the database upgrade completes and product services are enabled, Studio tests the environment and configuration, and then generates an HTML report. If problems are identified, you can restore the database backup. After resolving issues, you can upgrade the database again.
Upgrade the database and site automatically:
Launch the newly upgraded Studio. After you choose to start the site upgrade automatically and confirm that you are ready, the database and site upgrade proceeds.
Upgrade the database and site manually:
Launch the newly upgraded Studio. Choose to upgrade the site manually. The wizard checks for License Server compatibility and requests confirmation. After you confirm that you have backed up the database, the wizard generates and displays the scripts and a checklist of upgrade steps.
If a database’s schema does not change since the product version being upgraded, that script is not generated. For example, if the logging database schema does not change, the UpgradeLoggingDatabase.sql script is not generated.
Run the following scripts in the order shown.
- DisableServices.ps1: PowerShell script to be run by the Studio user on a Controller to disable product services.
- UpgradeSiteDatabase.sql: SQL script to be run by the database administrator on the server containing the Site database.
- UpgradeMonitorDatabase.sql: SQL script to be run by the database administrator on the server containing the Monitor database.
- UpgradeLoggingDatabase.sql: SQL script to be run by the database administrator on the server containing the Configuration Logging database. Run this script only if this database changes (for example, after applying a hotfix).
- EnableServices.ps1: PowerShell script to be run by the Studio user on a Controller to enable product services.
After completing the checklist tasks, click Finish upgrade.