Upgrade StoreFront
Upgrading preserves your StoreFront configuration and leaves users’ favorites intact. By contrast, uninstalling StoreFront removes StoreFront and associated services, sites, favorites (on stand-alone servers), and associated configuration.
Supported upgrade paths
You can upgrade to StoreFront 1912 latest CU from:
- StoreFront 1912 LTSR (initial release or any CU)
- StoreFront 1909
- StoreFront 1906
- StoreFront 1903
- StoreFront 1811
- StoreFront 3.16
- StoreFront 3.12 LTSR (any CU)
- StoreFront 3.0.1 LTSR (any CU)
To upgrade from versions prior to 3.0.1 you must first upgrade to StoreFront 3.12.
Warning:
When you upgrade from versions prior to 1912, any Desktop Appliance sites in your deployment are automatically removed. As an alternative, Citrix recommend using Citrix Workspace app Desktop Lock for all non-domain-joined use cases.
Good to know
- StoreFront does not support multiple server deployments containing different product versions, so all servers in a server group must be upgraded to the same version before you grant access to the deployment.
- Concurrent upgrade is not supported for multiple server deployments, servers must be upgraded sequentially.
- Before the StoreFront upgrade runs it performs some pre-upgrade checks. If any pre-upgrade check fails, the upgrade does not start and you are notified of the failures. Your StoreFront installation remains unchanged. After fixing the cause of the failures, rerun the upgrade.
- If the StoreFront upgrade itself fails, your existing StoreFront installation may lose its initial configuration. Restore your StoreFront installation to a functional state then rerun the upgrade. To restore StoreFront to a functional state consider the following approaches:
- restoring the VM snapshot you created before the upgrade,
- importing the StoreFront configuration you exported before the upgrade (see Export and import the StoreFront configuration,
- performing the troubleshooting advice in Troubleshoot StoreFront upgrade issues.
- Any StoreFront upgrade failures which occur from the Citrix Virtual Apps and Desktops metainstaller are reported in a dialog, with a link to the relevant failure log.
Get ready to upgrade
Before you start the upgrade, we recommend that you perform the following steps which can prevent upgrade failure:
- Plan your backup strategy before upgrading.
- Verify that you are upgrading from a supported version.
- Download the StoreFront installer from the Citrix website.
Upgrade a single StoreFront server
- Back up the server by creating a VM snapshot.
- Export the existing StoreFront configuration. If you have multiple servers in a server group then only export the server group configuration from one server. Provided you have propagated all changes between them, all servers in a server group maintain identical copies of the configuration. This backup allows you to easily build a new server group. so that you can easily restore the configuration in case of issues. Note that you will only be able to restore this backup into a server running the same version it was exported from.
- 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. - Prevent users from connecting by removing the server from any load balancer or otherwise blocking connections.
- Restart the server.
- Ensure that there are no applications running including StoreFront management console, Command line and PowerShell windows or any other applications that could have a lock on StoreFront files. This ensures that all StoreFront files are accessible by the installer during the upgrade. If the installer cannot access any files, they are not replaced and the upgrade fails, resulting in the removal of the existing StoreFront configuration.
- Ensure you do not have any Windows explorer or command prompts open on directories that contain StoreFront files.
- Disable any anti-virus applications.
- Run the installation file for the required version of StoreFront.
To upgrade a StoreFront server group
Upgrading StoreFront server groups involves using one of the servers to remove the other servers from the group. The removed servers retain configuration related to the group, which can prevent them being joined to a new server group. Before they can be reused to build new server groups, or as standalone StoreFront servers, they must be reset to factory defaults, or have StoreFront reinstalled on them. Simultaneously upgrading the servers in a StoreFront server group is not supported.
Example 1: Upgrade a three-node StoreFront server group during scheduled maintenance downtime
This describes upgrading a StoreFront server group of three servers A, B, and C, during scheduled downtime.
- Disable user access to the server group by disabling the load balancing URL. This prevents users from connecting to the deployment during the upgrade process.
-
Use server A to remove servers B and C from the group.
Servers B and C are now ‘orphaned’ from the server group.
- Upgrade server A by following the instructions in Upgrade a single StoreFront server.
- Ensure that server A has been successfully upgraded.
- On servers B and C, uninstall the currently installed version of StoreFront, then install the new version of StoreFront.
-
Join servers B and C to the upgraded server A to create an upgraded server group. This server group consists of one upgraded server (A) and two freshly installed servers (B and C).
The Join existing server group process automatically propagates all configuration data and subscription data to new servers B and C.
- Check all servers are functioning correctly.
- Enable user access to the upgraded server group by enabling the load balancing URL.
Example 2: Upgrade a three-node StoreFront server group without scheduled downtime
This describes upgrading a StoreFront server group of three servers A, B, and C, without scheduled downtime.
Before upgrading a server group:
- Export the StoreFront configuration using Export-STFConfiguration. This backup is necessary because servers are factory reset later in the process, which deletes configuration data.
- Export subscription data from server A using Export-STFStoreSubscriptions. This backup is necessary because servers are factory reset later in the process, which deletes subscription data. See Manage subscription data for a store.
- Disable user access to server C by removing it from the load balancer. This prevents users from connecting to server C during the upgrade process. The load balancer continues to send requests to servers A and B.
- Use server A to remove server C from the group. Servers A and B continue to provide access to your users’ resources. Server C is now orphaned from the server group, and is factory reset.
- Reset the orphaned server C to factory defaults using Clear-STFDeployment.
- Import the StoreFront configuration you previously exported into server C using Import-STFConfiguration. Server C now has an identical configuration to the old server group. It is not necessary to repeat this step again later. Only one server needs a copy of the configuration data to propagate it to any other servers that join the group.
- Upgrade server C by following the instructions in Upgrade a single StoreFront server. Server C now has an identical configuration to the old server group, and is upgraded to a new version of StoreFront.
- Import the subscription data which you exported previously into server C. It is not necessary to repeat this step again later. Only one server needs a copy of the subscription data to propagate it to any other servers that join the group.
- Repeat steps 3, 4, 5, and 7 using server B (do not repeat step 6). During this time, only server A is providing users with access to resources. It is therefore recommended to do this step during quiet working periods, where load on the StoreFront server group is expected to be minimal.
- Join server B to server C using the Join existing server group process. This gives a single server deployment on the current version of StoreFront (server A), and a new two-node server group on the new StoreFront version (servers B and C).
- Add servers B and C to the load balancing service so they can take over from server A.
- Remove server A from the load balancer so that users are directed to the newly upgraded servers B and C.
- Repeat steps 5, 7, 10 and 11 using server A (do not repeat step 6). The server group upgrade process is now complete. Servers A, B, and C have identical configuration and subscription data from the original group.
Note:
During the brief period when server A is the only accessible server, subscriptions can be lost (step 9). This can cause the new server group to have a slightly outdated copy of the subscription database after upgrade, and any new subscription records to be lost.
This has no functional impact because subscription data is not essential for users to be able to log on and launch resources. Users would, however, need to subscribe to a resource again after server A is factory reset and joined to the newly upgraded group. Although it is unlikely that more than a few subscription records would ever be lost, it is a possible consequence of upgrading a live StoreFront production environment with no downtime.
If the upgrade fails
-
In C:\Windows\Temp\StoreFront, open the latest CitrixMsi*.log and search for any exception errors.
Thumbs.db Access exceptions: caused by thumbs.db files inside C:\inetpub\wwwroot\citrix or in its subdirectories. Delete any thumbs.db files found.
Cannot get exclusive file access \in use exceptions: restore the snapshot/backup if available, or restart the server, and manually stop any StoreFront services.
Service cannot be started exceptions: restore the snapshot/backup if available, or install the full version of .NET framework 4.5 (not client profile).
- If there are no exception errors in CitrixMsi*.log, check the server’s Event Viewer > Delivery Services for any errors containing the preceding exception error messages. Follow the corresponding advice.
- If there are no exception errors in the Event Viewer, check the Admin logs in C:\Program Files\Citrix\Receiver StoreFront\logs for any errors containing the preceding exception error messages. Follow the corresponding advice.
For more details of logs files, see Installation Logs.