Product Documentation

Upgrade and migrate

Dec 07, 2016

This section contains procedures for upgrading Profile management software and information about transitioning your existing Windows user profiles to Citrix user profiles. For example, you can easily upgrade from Version 3.x to Version 5.x using those procedures.

Before upgrading, understand which Profile management features and settings are available in the release you are upgrading from and to. To review this information, see Profile management policies. To facilitate upgrades from .ini files to Group Policy, that topic also maps the setting names in the .ini file to those in the .adm and .admx files.

Do not configure Profile management (either in Group Policy or with the .ini file) while upgrading. Separate these two tasks by upgrading your deployment first and then configuring settings as required, ideally by answering the questions in Decide on a configuration.

Tip: You can hotfix your deployment of Profile management 2.1.1 or later by upgrading to the latest version. After upgrading, you can, if desired, enable any later feature.

Mixed Deployments

For deployments in which different versions of Profile management coexist, you should:

  • Minimize the time that a mixed deployment exists
  • Add the latest version's .adm or .admx file to each Group Policy Object on all domain controllers, ensuring all new features are disabled and allowing time for the new policies to propagate
  • Upgrade all computers to the latest version of Profile management before enabling any policy

Mixed deployments that contain Versions 5.x and 3.2 are supported. However, treat such deployments as a temporary state that exists during migration from the earlier version to the later one.

Important: Deployments that contain Version 5.x with Version 2.1.1 or any earlier version, including Citrix Technical Preview or beta releases, are unsupported. However, if you cannot upgrade, and those versions must coexist in your deployment, you may find the rest of this topic helpful.

Mixed Deployments Involving Profile Management 2.1.1 or Earlier

The rest of this topic contains information on the coexistence of Profile management 2.1.1 or earlier, and Profile management 3.x, or 5.x. It tells you how to migrate from one version to the other. In this topic, the terms Version 2 and Version 5 are used as shorthand for these versions.

Isolate each version in a separate OU and maintain separate user stores for the computers running each version. Alternatively, if a single user store serves computers running both versions, ensure all Version 5 settings are disabled until all the computers have been upgraded to Version 5. After you enable any Version 4 setting in a "mixed" user store, users can still log on to a computer that runs Version 2, but they receive a temporary Windows user profile (not their network, Citrix user profile) and changes they make to that profile are not saved. This is why you should consider mixed deployments to be temporary, and minimize the time they exist before completing the upgrade.

Using separate OUs and user stores can be inconvenient. To avoid these constraints, you can use one of the following two strategies. You configure each group in the appropriate version of Profile management using the Processed groups setting. Strategy 2 is more work than Strategy 1 because, with the former, you keep updating the Version 5 processed user groups and maintain two sets of applications and desktops (but you can automate by exporting application definitions from XenApp). The advantage is that you can take your time over the migration.

Note: As an alternative to the following strategies, with Windows Server 2008 Active Directory you can use WMI filtering to apply a GPO to a subset of computers in an OU, and determine which version of Profile management is installed. This allows you to automatically adjust which policy is applied, to match the version.

Strategy 1: One-off Migration

This scenario assumes that some downtime is acceptable. All computers are migrated at the same time.

The migration strategy is:
  1. Replace the Version 2 ADM file with the Version 5 file. The latter is compatible with the earlier version, so Version 2 computers continue to operate normally.
  2. Ensure all of the Version 5 settings are disabled. Do not rely on the default Not enabled.
  3. Start upgrading all the computers from Version 2 to Version 5. Fit this in with your normal maintenance and update schedules. With one exception, Version 5 acts as Version 2 until you enable any Version 5 setting. The exception is as follows. It is rare but more likely to occur if this upgrade step is staggered over a long time. If a user accesses their Citrix user profile from multiple servers, multiple Version 4 sessions are created. For example, they first use a workstation to access a virtual desktop on one server and then a laptop to access a published application on another. Profile management must use the pending area for the second, laptop session. At this point, the entire OU is treated as a Version 5 deployment (albeit one without any configured Version 5 features) and PmCompatibility.ini is updated to reflect this.
  4. Optionally, set your Version 5 processed users group to include only the members of a small pilot group. Wait for the AD Group Policy changes to propagate throughout the network (for example, over a weekend). You do not need to prevent access for any other users while this is happening. Back up the profiles of the pilot group. Then let the pilot group test Profile management.
  5. When you are happy with the pilot group results, ensure that you have backed up the other users' profiles.
  6. Use the next scheduled maintenance period to add the remaining users to the Version 5 processed users group. Allow sufficient time for the AD Group Policy changes to propagate, and let the remaining users log on.

Strategy 2: Phased Migration

This scenario assumes that you cannot move all your machines or your users to the new version in one go, so you select subsets of users that you migrate in batches. It suits deployments with several datacenters or geographically distributed users.

The migration strategy is:
  1. Replace the Version 2 ADM file with the Version 5 file. The latter is compatible with the earlier version, so Version 2 computers continue to operate normally.
  2. Ensure all of the Version 5 settings are disabled. Do not rely on the default Not enabled.
  3. Upgrade a few computers (the first batch) to Version 5. Alternatively, install Version 5 on new computers. By default, your Version 5-processed users group contains an empty group, so no user is processed as a Version 5 user. Be aware of the exception described in Strategy 1, which may also apply when you upgrade computers in a phased migration.
  4. Publish new applications (using XenApp) or virtual desktops (using XenApp or XenDesktop) from your Version 5 computers. These applications and desktops are identical to the ones previously published from your Version 2 computers, except for their names, which identify them as for use by Version 5 users.
  5. The selected users in this batch log on to the applications or desktops (for example, using Web Interface). They choose the new applications. (Use Web Interface to enforce this, based on user name or group membership). As a result, their sessions run on the Version 4 computers but they are processed with Version 2 settings.
  6. Ensure that you have backed up all users' profiles.
  7. Move the users out of the Version 2 processed users group and into the Version 4 group. Wait for the AD Group Policy changes to propagate to the Version 5 computers. Next time they log on, the users' sessions are processed with Version 5 settings.
  8. Upgrade the next batch of computers and migrate the next batch of users, as above.