Upgrade a deployment

Note:

This article covers upgrades for deployments involving Web Studio. For information about upgrades involving Citrix Studio, see the equivalent article in Citrix Virtual Apps and Desktops 7 2212 or earlier.

Introduction

You can upgrade certain deployments to newer versions without having to first set up new machines or sites. This is called an in-place upgrade. To learn which Citrix Virtual Apps and Desktops versions you can upgrade, see the Citrix Upgrade Guide.

Before you upgrade to any of the Citrix Virtual Apps and Desktops releases, ensure that your current Customer Success Services dates are valid and have not expired. For more information, see the Customer Success Services renewal licenses article.

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.

You can upgrade any component that can be installed with the full-product installer (and the standalone VDA installers), 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.

Upgrade sequence

The following diagram shows the steps the upgrade sequence. Upgrade procedure contains details of each step in the diagram.

Note:

To avoid failures, you must upgrade all Delivery Controllers and database before performing any of the provisioning and delivery group related tasks such as creating a new machine catalog, deleting a machine catalog, updating a machine in a delivery group, and so on.

Hybrid Rights Licenses

Hybrid Rights licenses are term-based subscription licenses that are provided, in addition to the cloud service subscription, when a customer transitions or trades up from a perpetual license to a cloud service subscription. You can also purchase a Hybrid Rights add-on with your DaaS subscriptions.

If you have a Hybrid Rights license with a SaaS attribute, when you upgrade to Citrix Virtual Apps and Desktops LTSR 2203 and later, you become eligible to access capabilities not available with Citrix Virtual Apps and Desktops LTSR 1912. These capabilities include provisioning and hosting workloads in public clouds, such as Microsoft Azure, AWS EC2, and Google Cloud. Before deploying the new license file, update your License Server to the most recent version.

If you have access to a Hybrid Rights license with no SaaS attribute, follow these steps to get access to the new Hybrid Rights license with SaaS attribute:

Note:

• You get an email with a new license code. For more information see, Use license access code.
• Your existing licenses are rescinded. Rescinded licenses must be deleted from License Servers followed by new license installation. For more information, see Deleting license files.

1. Go to citrix.com Manage Licenses portal and download the new Hybrid Rights license file with cloud provisioning rights enabled (SaaS attribute). For more information, see Download licenses. The following image shows the Hybrid Rights license file with SaaS attribute in the Increments section.

   

2. Install the Hybrid Rights license file on the License Server. For more information, see Install licenses.
3. If there is a change in license editions or model, make sure you run the broker command to set the edition and the model and then start the in-place upgrade. For more information about Broker commands, see Broker PowerShell SDK section.

For more information about public cloud support with Citrix Virtual Apps and Desktops Current Releases and Long Term Service Releases, see CTX270373.

Upgrade procedure

Most of the main product components can be upgraded by running the product installer on the machine containing the component.

If one machine contains more than one component (for example, Studio and License Server), all components on that machine are upgraded, if the product media contains newer versions of their software.

To use the installers:

• To run the full product installer’s 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.

Step 1: Prepare

Before you begin an upgrade, make sure you’re ready. Read and complete any necessary tasks:

• Remove PVD, AppDisks, and unsupported hosts
• VDAs that have PvD or AppDisk components
• Limitations
• Mixed environment considerations
• Earlier operating systems
• Preparation
• Preliminary site tests
• SQL Server version check

Step 2: Upgrade License Server

If the installation has a new version of the Citrix License Server software, upgrade this component first before any other components.

If you have not yet determined whether your License Server is compatible with the new version, it is essential that you run the installer on the License Server before upgrading any other core components.

Step 3: Upgrade StoreFront

If the installation media contains a new version of the StoreFront software, run the installer on the machine containing the StoreFront server.

• In the graphical interface, choose Citrix StoreFront from the Extend deployment section.
• From the command line, run CitrixStoreFront-x64.exe, which is available in the Citrix Virtual Apps and Desktops installation media’s x64 folder.

Step 4: Upgrade Director

If the installation media contains a new version of the Director software, run the installer on the machine containing Director.

Step 5: Upgrade Citrix Provisioning

The Citrix Provisioning installation media is available separately from the Citrix Virtual Apps and Desktops installation media. To learn how to install and upgrade Citrix Provisioning server and target device software, see the Citrix Provisioning product documentation.

Step 6: Upgrade half of Delivery Controllers

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

Step 7: Upgrade Studio

If you haven’t already upgraded Studio (because it was on the same machine as another component), run the installer on the machine containing Studio.

Note:

After you upgrade Web Studio, the version information might not update immediately. You might be prompted to upgrade Web Studio even though it’s already up to date. To address the issue, go to the Web Studio server, open Internet Information Services (IIS) Manager, navigate to Start Page > Sites > Default Web Site, and select Restart in the Manage Website pane.

Step 8: Restart Studio

Restart the upgraded Studio. The upgrade process automatically resumes.

Step 9: Upgrade database and site

Note:

To avoid failures, you must upgrade all Delivery Controllers and database before performing any of the provisioning and delivery group related tasks such as creating a new machine catalog, deleting a machine catalog, updating a machine in a delivery group, and so on.

Check Preparation for the permissions required to update the schema of the SQL Server databases.

• If you have sufficient permission to update the SQL Server database schema, you can initiate an automatic database upgrade. Continue with Upgrade the database and site automatically.
• If you do not have sufficient database permissions, you can initiate a manual upgrade that uses scripts, and proceed with the help of your database administrator (someone who has the required permissions). For a manual upgrade, the Studio user generates the scripts and then runs the scripts that enable and disable services. The database administrator runs other scripts that update the database schema, using either the SQLCMD utility or the SQL Server Management Studio in SQLCMD mode. Continue with Upgrade the database and site manually.
• If you have a multi-zone deployment and want to upgrade the database and site automatically, Citrix recommends that the dbschema upgrade should be performed in the same zone that hosts the SQL server databases of the site. Otherwise, upgrading the database and site automatically might fail.

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.

Upgrade the database and site automatically

1. Start the newly upgraded Studio.
2. Indicate that you want to start the site upgrade automatically and confirm that you are ready.

The database and site upgrade proceeds.

Upgrade the database and site manually

1. Start the newly upgraded Studio.
2. Indicate that you want to upgrade the site manually. The wizard checks for License Server compatibility and requests confirmation.

3. 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 has not changed 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.

4. Run the following scripts in the order shown.

   • DisableServices.ps1: The Studio user runs this PowerShell script on a Controller to disable product services.
   • UpgradeSiteDatabase.sql: The database administrator runs this SQL script on the server containing the Site database
   • UpgradeMonitorDatabase.sql: The database administrator runs this SQL script on the server containing the Monitor database.
   • UpgradeLoggingDatabase.sql: The database administrator runs this SQL script on the server containing the Configuration Logging database. Run this script only if this database changes (for example, after applying a hotfix).
   • EnableServices.ps1: The Studio user runs this PowerShell script on a Controller to enable product services.

   After the database upgrade completes and product services are enabled, Studio automatically 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.

5. After completing the checklist tasks, click Finish upgrade.

Step 10: Upgrade remaining Delivery Controllers

From the newly upgraded Studio, select Citrix Studio site-name in the navigation pane. On the Common Tasks tab, select Upgrade remaining Delivery Controllers.

Note:

To make Upgrade remaining Delivery Controllers available, create at least one machine catalog and one delivery group for the site.

After completing the upgrade and confirming completion, close and then reopen Studio. Studio might prompt for an extra site upgrade to register the Controller’s services to the site, or to create a zone ID if it does not exist.

Step 11: Upgrade VDAs

Important:

If you’re upgrading a VDA to version 1912 or later, see Upgrading VDAs to 1912 or later.

Run the product installer on machines containing VDAs.

If you used Machine Creation Services and a master image to create machines, go to your host and upgrade the VDA on the master image. You can use any of the available VDA installers.

• For graphic interface guidance, see Install VDAs.
• For command line guidance, see Install using the command line.

If you used Citrix Provisioning to create machines, see the Citrix Provisioning product documentation for guidance about upgrading.

Step 12: Update machine catalogs and Delivery Groups

• Update catalogs that use machines with upgraded VDAs.
• Upgrade catalogs that use machines with upgraded VDAs.
• Upgrade Delivery Groups that use machines with upgraded VDAs.

Step 13: After the upgrade

Upgrade other components in your deployment. For guidance, see the following product documentation:

• StoreFront
• AppDNA
• Citrix App Layering
• HDX RealTime Optimization Pack
• Profile Management
• Citrix Provisioning
• Session Recording
• Workspace Environment Management

If you need to replace the Microsoft SQL Server Express LocalDB software with a later version, see Replace SQL Server Express LocalDB.

Dbschema upgrade

When you update your deployment, several database schemas can be upgraded. The following table lists which database schemas are upgraded in the process:

Definition of terms:

• Site: Site Datastore. Dbschema update is made to the Site Datastore.
• Monitor: Monitor Datastore. Dbschema update is made to the Monitor Datastore.
• Config: Configuration table. Desktop Studio version, Licensing information, or both are updated in the Configuration table.
• Logging: Logging Datastore. Dbschema update is made to the Logging Datastore.

Upgrade VDAs to 2203 or later

If the Personal vDisk (PvD) component was ever installed on a VDA, that VDA cannot be upgraded to version 2203 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.

Here’s how the PvD component 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 /baseimage option 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 (2203 or later) on the machine or image.

• If PvD is installed, a message appears, indicating there is an incompatible component.
  • From 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:

1. Uninstall the current VDA.
2. Install the new VDA.

If you want to continue using PvD on your Windows 10 (1607 and earlier, without updates) machines, VDA 7.15 LTSR is the latest supported version.

Note:

Can I use Personal vDisk with Windows 7 desktops in XenApp and XenDesktop 7.15 LTSR?

Citrix excluded Personal vDisk (PvD) from XenApp and XenDesktop 7.6 LTSR which was announced in January 2016. Additionally, Citrix has announced the deprecation of the PvD technology and recommends that customers start using Citrix App Layering going forward. Citrix App Layering (version 4.4 and later) is a compatible component of XenApp and XenDesktop 7.15 LTSR. However, to help customers with existing PvD deployments on Windows 7 migrate to Citrix App Layering technology, Citrix has decided to provide limited time support for PvD deployments for Windows 7 desktops through XenApp and XenDesktop 7.15 LTSR Cumulative Updates (CUs) until Jan 14, 2020. The PvD component will be removed from LTSR CUs and not supported after Jan 14, 2020. Additionally, use of PvD for Windows 7 beyond Jan 14, 2020 will render LTSR sites non-compliant. Also, PvD for Windows 10 continues to be excluded from 7.15 LTSR. Therefore, customers should not use it with their 7.15 LTSR sites.

Remove PvD, AppDisks, and unsupported hosts

The following technologies and host types are not supported in Citrix Virtual Apps and Desktops 7 Current Release deployments:

• Personal vDisks (PvD) for storing data next to users’ VMs in catalogs. The user personalization layer feature now handles user persistence.
• AppDisks for managing applications used in Delivery Groups.
• Host types: Azure Classic, CloudPlatform (the original Citrix product).
  • For host types supported in this release, see System requirements.
  • For information about alternative ways you can continue using ARM and AWS, see CTX270373.

If your current deployment uses PvDs or AppDisks, or has connections to unsupported host types (for example, Microsoft Azure Classic), you can upgrade to version 2006 (or later supported versions) only after removing items that use those technologies. If your current deployment uses public cloud host connections (for example, AWS), ensure that you have Hybrid Rights License before upgrading. When the installer detects one or more of the unsupported technologies or host connections without Hybrid Rights License, the upgrade pauses or stops, and an explanatory message appears. The installer logs contain details.

To help ensure a successful upgrade, review and follow the applicable guidance for removing the unsupported items.

• Remove PvD
• Remove AppDisks
• Remove unsupported host items

Even if you did not use PvD or AppDisks in your deployment, related MSIs might have been included in an earlier VDA installation or upgrade. Before you can upgrade your VDAs to version 2006 (or a later supported version), you must remove that software, even if you never used it. When using the graphical interface, that removal can be done for you, or you can include removal options when using the CLI. For details, see Upgrading VDAs that have PvD or AppDisks components.

Remove PvD

A deployment upgrade cannot succeed until you remove all machines that are configured to use PvD. This affects catalogs and Delivery Groups.

To remove PvD from groups and catalogs:

1. From Studio, if a Delivery Group contains machines from a catalog that uses PvD, remove those machines from the group.
2. From Studio, delete all catalogs containing machines that use PvD.

VDA upgrades: The deployment upgrade does not detect whether VDAs have the AppDisk or PvD components installed. However, the VDA installers do. For details, see VDAs that have PvD or AppDisks components.

If you plan to use App Layering instead of PvD, see Migrating PvD to App Layering for information about moving data.

Remove AppDisks

A deployment upgrade cannot proceed until you remove AppDisks from all Delivery Groups that use them, and then remove the AppDisks themselves.

1. Select Delivery Groups in the Studio navigation pane.
2. Select a group and then click Manage AppDisks in the Action pane.
3. Click the action that removes the AppDisk from the group.
4. Repeat steps 2 and 3 for each Delivery Group that uses AppDisks.
5. Select AppDisks in the Studio navigation pane.
6. Select an AppDisk and click the action that deletes the AppDisk.
7. Repeat steps 5 and 6 for each AppDisk.

VDA upgrades: The deployment upgrade does not detect whether VDAs have the AppDisk or PvD components installed. However, the VDA installers do. For details, see VDAs that have PvD or AppDisks components.

Remove unsupported host items

A deployment upgrade to version 2006 (or later supported version) cannot proceed if the site has connections to unsupported host types, such as Citrix CloudPlatform or Microsoft Azure Classic. Complete the following tasks before attempting an upgrade.

From Studio:

• Delete all connections to unsupported hosts.
• If a Delivery Group contains machines from a catalog created with a master image from an unsupported host, remove those machines from the group.
• Delete all catalogs that were created using a master image from an unsupported host.

VDAs that have PvD or AppDisks components

If the components that enable PvD and AppDisks technologies are installed on a VDA, that VDA cannot be upgraded until those components are removed.

Note:

When upgrading to version 1912, you had to uninstall the current VDA and then install the new VDA. In this version, you’re asked if you want Citrix to remove the component and then continue the upgrade.

The AppDisk and PvD components might have been installed in earlier VDA versions, even if you never used those technologies:

• Graphical interface: In the VDA installers, the Additional Components page contained the Citrix AppDisk / Personal vDisk option. 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 that offered it), that component was installed.
• CLI: Specifying the /baseimage option installed the component.

What to do

If the VDA installer does not detect the AppDisks or PvD components in the currently installed VDA, the upgrade proceeds as usual.

If the installer detects AppDisks or PvD components in the currently installed VDA:

• Graphical interface: The upgrade pauses. A message asks if you want the unsupported components removed automatically. If you click OK, the components are removed automatically and the upgrade proceeds.

• CLI: To avoid command failure, include the following options in the command:

  • /remove_appdisk_ack
  • /remove_pvd_ack

Limitations

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

• Early Release or Technology Preview versions: You cannot upgrade from an 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 more information, see Earlier operating systems.

• Mixed environments/sites: If you must continue to run earlier version sites and current version sites, see Mixed environment considerations.

• Product selection: When you upgrade from an earlier version, you do not choose or specify the product (Citrix Virtual Apps or Citrix Virtual Apps and Desktops) that was set during the installation.

Mixed environment considerations

When you upgrade, Citrix recommends that you upgrade all components and VDAs so that you can access all the new and enhanced features in your edition and version.

For example, although you can use current VDAs in deployments containing earlier Controller versions, new features in the current release might not be available. VDA registration issues can also occur when using non-current versions.

In some environments, you might 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. (This is called the functional level.) By default, this setting specifies the minimum recommended VDA version. The default value is sufficient for most deployments. Consider changing the setting to an earlier version only if the catalog contains VDAs earlier than the default. Mixing VDA versions in a machine catalog is not recommended.

If a catalog is created with the default minimum VDA version setting, and one or more machines has a VDA earlier than the default version, those machines cannot register with the Controller, and will not work.

For more information, see VDA versions and functional levels.

Multiple sites with different versions

When your environment contains sites with different product versions (for example, a XenDesktop 7.18 site and a Citrix Virtual Apps and Desktops 1909 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.

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 supported for the current version of the component.

For example, assume that you installed a server VDA on a Windows Server 2008 R2 machine. Now you want to upgrade that VDA to the current release, but Windows Server 2008 R2 is not supported in the current release you’re upgrading to.

If 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”.

These considerations apply to upgrading Current Release and Long Term Service Release versions. (It does not affect applying CUs to an LTSR version.)

Follow the links to learn which OSs are supported:

• Citrix Virtual Apps and Desktops (Current Release):
  • 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.

Windows XP and Windows Vista are not valid for any 7.x components or technologies.

* Applies to Delivery Controller, Studio, Director, and VDAs.

What you can do

You have choices. You can:

• Continue with the current OS
• Reimage or upgrade the machine
• Add new machines and then remove old machines

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, 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 (this includes internal upgrades to your OS. For example, Windows 10 version 1903 to Windows 10 version 1909). Otherwise, the Citrix software will be in an unsupported state. Then, install the new component.
• To upgrade the OS in a VDA machine without reimaging, you must first install a version of the VDA that is supported on the OS that you are upgrading to or upgrade the VDA after upgrading the OS. Otherwise, the Citrix software will be in an unsupported state.

Add new machines and then remove old machines

This method is feasible if you must upgrade the OS on machines containing 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.

1. Take a snapshot of all Delivery Controllers in the site and then back up the site database.
2. Install new Delivery Controllers on clean servers with supported operating systems. For example, install a Controller on two Windows Server 2016 machines.
3. Add the new Controllers to the site.
4. 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.

Preparation

Before beginning an upgrade, review the following information and complete necessary tasks.

Note:

Although upgrading VDAs occurs later in the upgrade sequence, it’s a good idea to choose an installer and review the procedure before you start the upgrade, so you know what to expect.

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.

Installation specifics: After you complete any preparation work and are ready to start the installer, the installation article shows you what you will see (if you’re using the graphical interface) or what to type (if you’re using the command-line interface).

• Install/upgrade core components using the graphical interface
• Install/upgrade core components using the command line
• Install/upgrade VDAs using the graphical interface
• Install/upgrade VDAs using the command line

If you originally installed a single-session 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.

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

Database actions

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.

For information about upgrading SQL Server versions that are no longer supported, see SQL Server version check. (This refers to the SQL Server that is used for the site, monitor, and configuration logging databases.)

Microsoft SQL Server Express LocalDB is installed automatically, for use with Local Host Cache. If you need to replace an earlier version, the new version must be SQL Server Express LocalDB 2019. For details about replacing SQL Server Express LocalDB with the new version after you upgrade the components and the site, see Replace SQL Server Express LocalDB.

Ensure that your Citrix licensing is up-to-date

For a comprehensive look at managing Citrix Licensing, see Activate, upgrade, and manage Citrix licenses.

You can use the full-product installer to upgrade the License Server. Or, you can download and upgrade the license components separately. See Upgrade.

Before upgrading, be sure your Customer Success Services / Software Maintenance / Subscription Advantage date is valid for the new product version. The date must be at least 2021.11.15.

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 a Delivery 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 display indicates whether the License Server is compatible. If the License Server is incompatible, upgrade the license server.

Back up any StoreFront modifications

Before starting an upgrade, if you have made modifications to files in C:\inetpub\wwwroot\Citrix\<StoreName>\App_Data, such as default.ica and usernamepassword.tfrm, back them up for each store. After the upgrade you can restore them to reinstate your modifications.

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.

Other preparation tasks

• Back up templates and upgrade hypervisors, if needed
• Complete any other preparation tasks dictated by your business continuity plan.

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
• Ensure you have Hybrid Rights License if you want to add public cloud host connections (for example, AWS). Otherwise, the preliminary site test pauses or stops, and an explanatory message appears.

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. In most cases, if you include the /ignore_site_test_failure option, any test failures are ignored and the upgrade proceeds. (See SQL Server version check for exceptions.)

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.

SQL Server version check

A successful Citrix Virtual Apps and Desktops deployment requires a supported version of Microsoft SQL Server for the site, monitor, and configuration logging databases. Upgrading a Citrix deployment with a SQL Server version that’s no longer supported can result in functionality issues, and the site will be unsupported.

To learn which SQL Server versions are supported for the Citrix release you’re upgrading to, see the System requirements article for that release.

When upgrading a Controller, the Citrix installer checks the currently installed SQL Server version used for the site, monitor, and configuration logging databases.

• If the check determines that the currently installed SQL Server version is not a supported version in the Citrix release you’re upgrading to:

  • Graphical interface: The upgrade halts with a message. Click I understand and then click Cancel to close the Citrix installer. (You cannot continue with the upgrade.)
  • Command-line interface: the command fails (even if you included the /ignore_db_check_failure option with the command).

  Upgrade the SQL Server version, and then start the Citrix upgrade again.

• If the check cannot determine which SQL Server version is currently installed, see if your currently installed version is supported in the version you’re upgrading to (System requirements).

  • Graphical interface: The upgrade halts with a message.

    • If the currently installed SQL Server version is supported, click I understand to close the message, and then click Next to continue with the Citrix upgrade.
    • If the currently installed SQL Server version is not supported, click I understand to close the message, and then click Cancel to end the Citrix upgrade. Upgrade your SQL Server to a supported version and then start the Citrix upgrade again.

  • Command-line interface: The command fails with a message. After closing the message:

    • If the currently installed SQL Server version is supported, run the command again with the /ignore_db_check_failure option.
    • If the currently installed SQL Server version is not supported, upgrade your SQL Server to a supported version. Run the command again to start the Citrix upgrade.

Upgrading SQL Server

If you bring up new SQL Server servers and migrate the site database, then connection strings must be updated.

If the site currently uses SQL Server Express forthe site database (that Citrix installed automatically during site creation):

1. Install the latest SQL Server Express version.
2. Detach the database.
3. Attach the database to the new SQL Server Express.
4. Migrate connection strings.

For more information, see Configuring connection strings and the Microsoft SQL Server product documentation.

Replace SQL Server Express LocalDB

Microsoft SQL Server Express LocalDB is a feature of SQL Server Express that Local Host Cache uses on a standalone basis. Local Host Cache does not require any components of SQL Server Express other than SQL Server Express LocalDB.

If you installed a Delivery Controller version earlier than 1912 and then upgrade your deployment to version 1912 or later, Citrix does not automatically upgrade the SQL Server Express LocalDB version. Why not? Because you might have non-Citrix components that rely on SQL Server Express LocalDB. If you have non-Citrix components that are using SQL Server Express LocalDB, ensure that upgrading SQL Server Express LocalDB does not disrupt those components. To upgrade (replace) the SQL Server Express LocalDB version, follow the guidance in this section.

• When upgrading Delivery Controllers to Citrix Virtual Apps and Desktops versions 2203 LTSR or versions through 2311: The supported version is SQL Server Express LocalDB 2019.

  Note:

  The SQL Server Express LocalDB versions 2017, 2019, and 2022 are all compatible with each other. Therefore, it is not mandatory to upgrade SQL Server Express LocalDB for LHC to work.

What you need:

• The Citrix Virtual Apps and Desktops installation media containing a copy of Microsoft SQL Server Express LocalDB 2019.
• The PsExec tool from the Windows Sysinternals toolbox that you can download from Microsoft. See the Microsoft document PsExec v2.43.

Procedure:

1. Complete the upgrade of your Citrix Virtual Apps and Desktops components, databases, and site. (Those database upgrades affect the site, monitoring, and configuration logging databases. They do not affect the Local Host Cache database that uses SQL Server Express LocalDB.)
2. Log on to the Delivery Controller that is being used to recreate the LHC database.
3. On that Delivery Controller, download PsExec from Microsoft and place it in C:\Temp.
4. Stop the Citrix High Availability Service.

5. Open the command prompt, navigate to C:\Temp, and then run the following command to elevate the Command Prompt with Network Service account:

   psexec -i -u "NT AUTHORITY\NETWORKSERVICE" cmd
   <!--NeedCopy-->
   

6. Run whoami to confirm that the command prompt is running as the Network Service account. You must get the following output: nt authority\networkservice.

7. Use the command prompt to navigate to the SQL LocalDB instance:

   • If upgrading from SQL LocalDB 2014:

      cd "C:\Program Files\Microsoft SQL Server\120\Tools\Binn"
      <!--NeedCopy-->
     

   • If upgrading from SQL LocalDB 2017:

      cd "C:\Program Files\Microsoft SQL Server\140\Tools\Binn"
      <!--NeedCopy-->
     

8. Stop and delete SQL LocalDB instance: CitrixHA.

   SqlLocalDB stop CitrixHA
   
   SqlLocalDB delete CitrixHA
   <!--NeedCopy-->
   

9. Remove the related files in C:\Windows\ServiceProfiles\NetworkService.

   HADatabaseName.*
   HADatabaseName_log.*
   HAImportDatabaseName.* (if exists)
   HAImportDatabaseName_log.* (if exists)
   <!--NeedCopy-->
   

10. Uninstall your existing SQL LocalDB SQL Server Express from the server using the Windows feature for removing programs.
11. Install SQL Server Express LocalDB 2019. In the Support > SQLLocalDB folder on the Citrix Virtual Apps and Desktops installation media, double-click sqllocaldb.msi. A restart might be requested to complete the installation. The new SQL LocalDB resides in C:\Program Files\Microsoft SQL Server\150\Tools\Binn.
12. Start the Citrix High Availability Service on the Delivery Controller where you uninstalled the old SQL LocalDB version.
13. In Command Prompt, run SqlLocalDB i to confirm whether CitrixHA is created again or not.
14. Repeat the steps on the remaining Delivery Controllers.

15. Ensure that the Local Host Cache database is created on each Delivery Controller. This confirms that the High Availability Service (secondary broker) can take over, if needed.

    1. On the Controller server, browse to C:\Windows\ServiceProfiles\NetworkService.
    2. Verify that HaDatabaseName.mdf and HaDatabaseName_log.ldf are created.