Product Documentation

Upgrade a deployment

Aug 15, 2016

In this article:

  • Introduction
  • Which product component versions can be upgraded
  • Requirements, limitations, and preparation
  • Mixed environment consideratons
  • VDAs on machines running Windows XP or Windows Vista
  • VDAs on machines running Windows 8.x and Windows 7
  • Mixed VDA support
  • Upgrade sequence


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 (or a later version) to the latest released (current) XenDesktop version
  • From XenApp version 7.5 (or a later version) to the latest released (current) XenApp version

You can also use the current XenApp installer to upgrade a XenApp 6.5 worker server to a current 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.

In this content, the word product refers to XenApp 7.x or XenDesktop 7.x, unless otherwise noted.

Which product component versions can be upgraded

Using the product installer and Studio, you can upgrade:

  • Delivery Controllers 5 or later
  • VDA 5.0 SP1 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.
    • If the installer detects Receiver for Windows Enterprise (CitrixReceiverEnterprise.exe) on the machine, it is upgraded to Receiver for Windows Enterprise 3.4.
  • Director 1 or later
  • Database: This 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)
  • Personal vDisk

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.

Requirements, limitations, and preparation

  • You must use the product installer's graphical or command-line interface to upgrade core components and VDAs; you cannot import or migrate data from an earlier version.
  • 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, if an upgrade includes new versions of the Controller and Studio, and you upgrade only 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.
  • 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.0217.
  • You cannot upgrade XenDesktop Express Edition. Obtain and install a license for a currently supported edition, then upgrade it.
  • Before beginning any upgrade activity, back up the database, as described in CTX135207, so you can restore it if any issues are discovered after the database upgrade.
  • Optionally, back up templates and upgrade hypervisors, if used.
  • If you must continue to run earlier version Sites and current version Sites, see Mixed environment considerations.
  • If you have VDAs installed on Windows XP or Windows Vista machines, see VDAs on machines running Windows XP or Windows Vista.
  • If you do not plan to upgrade all VDAs to the latest version, review Mixed VDA support.
  • If your deployment includes Web Interface, Citrix recommends using StoreFront.
  • In addition to being a domain user, you must be a local administrator on the machines where you are upgrading product components.
  • Review the upgrade sequence below so you can plan for and mitigate potential outages.

You cannot upgrade:

  • From an Early Release or Technology Preview version
  • From a XenApp version earlier than 7.5 (except replacing XenApp 6.5 software on a server with a current VDA for Server OS; see Migrate XenApp 6.x)
  • From a XenDesktop version earlier than 5.6; see Migrate XenDesktop 4

When you upgrade, you do not choose or specify the product (XenApp or XenDesktop), which was set during the initial installation.

Mixed environment considerations

When your environment contains Sites and 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 within each Site, but make sure 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. See Mixed VDA considerations below.

  • 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. SeeCTX128580.
  • 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. 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. For example, to use the session prelaunch, session linger, and unauthenticated users features in the 7.6 release, the VDAs must have a minimum version of 7.6 installed.

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; you need to consider changing this setting only if the machine catalog contains machines with earlier VDA versions. However, mixing VDA versions in a machine catalog can have unintended effects

As noted above, if your deployment includes Windows XP and Windows Vista systems, you must use an earlier VDA version, and the machine catalog containing those machines must specify VDA version 5.6 FP1. The VDAs will register successfully with the Controller, but those machines will be unable to use many of the new features in the 7.x versions (including StoreFront). This also applies to any machines you add to that catalog that have 7.x version VDAs. The following graphic illustrates this.

In the above case, if you must continue to use older VDAs, place them in a machine catalog by themselves.

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, assume the most recent VDA version is 7.6. 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.

In this example, the machine with VDA 7.1 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 sequence

The upgrade sequence is illustrated below; descriptions follow. If components are installed on different machines, run the installer on each of those machines.


Upgrade components

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.

  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 (in the preferred order: License Server, StoreFront, and then Director).
  2. Upgrade the Provisioning Services servers and clients, using the guidance in the Provisioning Services documentation.
  3. Run the product installer on machines containing VDAs. Although you can upgrade VDAs before or after upgrading the Controllers, Citrix recommends you do so before, because it allows you to quickly enable new features after the upgrade.

    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 parameter: /EXCLUDE "Personal vDisk","Machine Identity Service". For example:

    C:\x64\XenDesktop Setup\XenDesktopVdaSetup.exe /EXCLUDE "Personal vDisk","Machine Identity Service"

  4. Run the product installer on half of the Controllers. (This will also upgrade 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.
  5. If Studio is installed on a different machine than one of the Controllers you upgraded in the previous step, run the installer on the machine where Studio is installed.
  6. From the newly upgraded Studio, upgrade the Site database. For details, see Upgrade the database and Site.
  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.
  8. After completing the upgrade and confirming completion, close and then reopen Studio.
  9. In the Site Configuration section of the Common Tasks page, select Perform registration. Registering the Controllers makes them available to the Site.
  10. After you select Finish when the upgrade completes, you are offered the opportunity to enroll in the Citrix Customer Experience Improvement Program (CEIP), which collects anonymous information about your deployment. That information is then used to improve product quality, reliability, and performance.
  11. After upgrading components, the database, and the Site, use Studio to:
    • 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.
    • Update all master images that use the upgraded VDA.
    • Upgrade Machine Catalogs and Delivery Groups.

Upgrade the Site database 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.

  • 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 the Databases article.
  • 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 using the SQL Management Studio in SQLCMD mode. Inaccurate errors may result otherwise.
Important: Citrix strongly recommends you back up the database 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 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: This process includes generating and running scripts.
  1. Launch the newly upgraded Studio. After you choose to manually upgrade the Site, 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.
  2. Run the following scripts in the order shown:
    Script Description
    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, using a tool such as SQL Server Management Studio.
    UpgradeMonitorDatabase.sql SQL script to be run by the database administrator on the server containing the Monitor database, using a tool such as SQL Server Management Studio.
    UpgradeLoggingDatabase.sql SQL script to be run by the database administrator on the server containing the Configuration Logging database, using a tool such as SQL Server Management Studio. 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.
  3. After you complete the displayed checklist tasks, select Finish upgrade.