Upgrade a deployment

May 09, 2017

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. You can upgrade:

  • From XenDesktop version 5.6 (or a later version) to the latest version of 7.6 LTSR
  • From XenApp version 7.5 to the latest version of 7.6 LTSR

You can also use the latest XenApp 7.6 LTSR installer to upgrade a XenApp 6.5 worker server to the latest XenApp 7.6 LTSR VDA for Windows Server OS. This is a supplementary activity to migrating XenApp 6.5; see Upgrade a XenApp 6.5 worker to a new VDA for Windows Server OS.

To start an upgrade, you run the installer from the new version to upgrade previously installed core components (Delivery Controller, Citrix Studio, Citrix Director, Citrix License Server) and VDAs. The installer determines which components require upgrading and then starts the upgrade at your command. After upgrading the components, you use the newly upgraded Studio to upgrade the Site database and the Site.

Be sure to review all the information in this article before beginning the upgrade.

Upgrade sequence

The following diagram summarizes the upgrade sequence. Details are provided in Upgrade procedure below. For example, if you have more than one core component installed on a server, running the installer on that machine will upgrade all components that have new versions. 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.

localized image

Which product component versions can be upgraded

Using the product installer and Studio, you can upgrade:

  • Citrix License Server, Studio, and StoreFront
  • Delivery Controllers 5.6 or later
  • VDA 5.6 or later
    • Unlike earlier VDA releases, you must use the product installer to upgrade VDAs; you cannot use MSIs.
    • If the installer detects Receiver for Windows (Receiver.exe) on the machine, it is upgraded to the Receiver version included on the product installation media.
  • Director 1 or later
  • Database: This Studio action upgrades the schema and migrates data for the Site database (plus the Configuration Logging and Monitoring databases, if you’re upgrading from an earlier 7.x version)

Using the guidance in the feature/product documentation, upgrade the following if needed:

  • Provisioning Services (for XenApp 7.x and XenDesktop 7.x, Citrix recommends using the latest released version; the minimum supported version is Provisioning Services 7.0).
    • Upgrade the Provisioning Services server using the server rolling upgrade, and the clients using vDisk versioning.
    • Provisioning Services 7.x does not support creating new desktops with XenDesktop 5 versions. So, although existing desktops will continue to work, you cannot use Provisioning Services 7.x to create new desktops until you upgrade XenDesktop. Therefore, if you plan a mixed environment of XenDesktop 5.6 and 7.x Sites, do not upgrade Provisioning Services to version 7.
  • Microsoft System Center Virtual Machine Manager SCVMM. The current product supports SCVMM 2012 and SCVMM 2012 SP1; XenDesktop 5.x supports earlier versions. Use the following upgrade sequence to avoid downtime:
    1. If you have Controllers running versions earlier than XenDesktop 5.6 FP1, upgrade them to XenDesktop 5.6 FP1 (see the XenDesktop documentation for that version).
    2. Upgrade the SCVMM server to SCVMM 2012; see the Microsoft documentation for instructions.
    3. Upgrade XenDesktop components to the current version.
    4. Optionally, upgrade the SCVMM server to SCVMM 2012 SP1.
  • StoreFront.


The following limits 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. If you do not plan to upgrade all VDAs to the latest version, review Mixed VDA support.

XenApp version 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.

Although you cannot upgrade a XenApp 6.5 farm, you can replace the XenApp 6.5 software on a Windows Server 2008 R2 machine with a current VDA for Server OS. See Upgrade a XenApp 6.5 worker to a new VDA.

XenDesktop version earlier than 5.6

You cannot upgrade from a XenDesktop version earlier than 5.6. 

XenDesktop Express Edition

You cannot upgrade XenDesktop Express edition. Obtain and install a license for a currently supported edition, and then upgrade it.

Early Release or Technology Preview versions

You cannot upgrade from a XenApp or XenDesktop Early Release or Technology Preview version.

Windows XP/Vista

If you have VDAs installed on Windows XP or Windows Vista machines, see VDAs on machines running Windows XP or Windows Vista

Product selection

When you upgrade from an earlier 7.x version, you do not choose or specify the product (XenApp or XenDesktop) 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.


Before beginning an upgrade:

Decide which interface to use

Use the installer’s graphical or command-line interface to upgrade core components and VDAs. You cannot import or migrate data from an earlier version.

Check your Site’s health

Ensure the Site is in a stable and functional state before starting an upgrade. If a Site has issues, upgrading will not fix them, and can leave the Site in a complex state that is difficult to recover from. To test the Site, select the Site entry in the Studio navigation pane. In the Site configuration portion of the middle pane, click Test site.

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.

Optionally, back up templates and upgrade hypervisors, if needed.

Complete any other preparation tasks dictated by your business continuity plan.

In a high availability environment, ensure that the Site, monitoring, and Configuration Logging databases are running on the primary database server before starting an upgrade.

Ensure your Citrix licensing is up to date

Before upgrading the Citrix License Server, be sure your 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 2016.0420.

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

Important: Before starting an upgrade, stop and disable any third-party monitoring agent services.

Ensure 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). If the Studio user does not have those permissions, initiating a manual database upgrade will generate 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.

Use StoreFront

If you deployment includes Web Interface, Citrix recommends using StoreFront.

Mixed environment considerations

When your environment contains Sites/farms with different product versions (a mixed environment), Citrix recommends using StoreFront to aggregate applications and desktops from different product versions (for example, if you have a XenDesktop 7.1 Site and a XenDesktop 7.5 Site). 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 Provisioning Services for both, either deploy a new Provisioning Services for use with the 7.x Site, or upgrade the current Provisioning Services 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.

  • Sites with Controllers at version 5.x and VDAs at version 7.x should remain in that state only temporarily. Ideally, you should 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.

VDAs on machines running Windows XP or Windows Vista

You cannot upgrade VDAs installed on machines running Windows XP or Windows Vista to a 7.x version. You must use VDA 5.6 FP1 with certain hotfixes; see CTX140941 for instructions. Although earlier-version VDAs will run in a 7.x Site, they cannot use many of its features, including:

  • Features noted in Studio that require a newer VDA version.
  • Configuring App-V applications from Studio.
  • Configuring Receiver StoreFront addresses from Studio.
  • Automatic support for Microsoft Windows KMS licensing when using Machine Creation Services. See CTX128580.
  • Information in Director:
    • Logon times and logon end events impacting the logon duration times in the Dashboard, Trends, and User Detail views.
    • Logon duration breakdown details for HDX connection and authentication time, plus duration details for profile load, GPO load, logon script, and interactive session establishment.
    • Several categories of machine and connection failure rates.
    • Activity Manager in the Help Desk and User Details views.

Citrix recommends reimaging Windows XP and Windows Vista machines to a supported operating system version and then installing the latest VDA.

VDAs on machines running Windows 8.x and Windows 7

To upgrade VDAs installed on machines running Windows 8.x or Window 7 to Windows 10, Citrix recommends reimaging Windows 7 and Windows 8.x machines to Windows 10 and then installing the supported VDA for Windows 10, using the standalone VDA installation package delivered with XenApp and XenDesktop 7.6 FP3. If reimaging is not an option, uninstall the VDA prior to upgrading the operating system, otherwise the VDA will be in an unsupported state.

Mixed VDA support

When you upgrade the product to a later version, Citrix recommends you upgrade all the core components and VDAs so 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 this scenario, 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 machine catalog is created with the default recommended VDA version setting, and any of the machines in the catalog has an earlier VDA version installed, those machines will not be able to register with the Controller and will not work. 

For example, you create a machine catalog with the default VDA setting: “7.6 (recommended, to access the latest features).” You add three machines to that catalog: two with VDA 7.6 and one with VDA 7.1. The VDA 7.1 machine will not register with the Controller. If you cannot upgrade that VDA, consider creating a separate machine catalog configured with a VDA setting of “version 7.0 or later” and adding that machine. Although that machine will not be able to take advantage of new 7.6 features, it will be able to register with the Controller.

Upgrade procedure

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, see Install using the command line.

Step 1. If more than one core component is installed on the same server (for example, the Controller, Studio, and License Server) and several of those components have new versions available, they will all be upgraded when you run the installer on that server.

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.

Step 2. If you use Provisioning Services, upgrade the PVS servers and target devices, using the guidance in the Provisioning Services documentation.

Step 3. Run the product installer on machines containing VDAs. (See Step 12 if you use master images and Machine Creation Services.)

When upgrading VDAs from an earlier 7.x version that are installed on physical machines (including Remote PC Access), use the command-line interface with the option /exclude “Personal vDisk”,”Machine Identity Service”. For example:

C:\x64\XenDesktop Setup\XenDesktopVdaSetup.exe /exclude “Personal vDisk”,”Machine Identity Service”

Step 4. Run the product installer on half of the Controllers. (This 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, the Site is inoperable during the upgrade.

Step 5. If Studio is installed on a different machine than one you’ve already upgraded, run the installer on the machine where Studio is installed.

Step 6. From the newly upgraded Studio, upgrade the Site database. For details, see Upgrade the databases and the Site below.

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

Step 8. After completing the upgrade and confirming completion, close and then reopen Studio.

Step 9. In the Site Configuration section of the Common Tasks page, select Perform registration. Registering the Controllers makes them available to the Site.

Step 10. After you select Finish when the upgrade completes, you are offered the opportunity to enroll in the Citrix telemetry programs, which collect information about your deployment. That information is used to improve product quality, reliability, and performance.

Step 11. After upgrading components, the database, and the Site, 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 were run automatically after you upgraded the database, but you can run them again at any time.

Step 12. 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. Then update machine catalogs that use those master images, and upgrade Delivery Groups that use those catalogs.

Upgrade the database and Site

After upgrading the core components and VDAs, use the newly upgraded Studio to initiate an automatic or manual database and Site upgrade.

  • 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).
  • If the Studio user does not have those permissions, initiating a manual database upgrade will generate 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. If the SQL scripts are run manually, they should be run using either the SQLCMD utility or the SQL Management Studio in SQLCMD mode. Inaccurate errors may result otherwise.

Important: Citrix strongly recommends you back up the databases before upgrading, as described in 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 databases 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 databases and Site manually

This process includes generating and running scripts.

Step 1. Launch the newly created Studio. After you choose to manually upgrade the Site, the wizard prompts to confirm that you have backed up the databases. Then, the wizard generates and displays the scripts and a checklist of upgrade steps.

Step 2. 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.

Step 3. After completing all the checklist tasks shown in the wizard, click Finish upgrade.

Dbschema upgrade

When you update your deployment to a new CU, several of your database schemas are upgraded. Consult the following table for information about which database schemas are being upgraded in the process:

localized image

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, License Server version, or both are updated in the Configuration table.

Upgrade a deployment

In this article