With the release of User Profile Manager by Citrix the structure of the managed user profiles and the user store has changed significantly. While this remodeling was necessary to enable key features in UPM, it presents a challenge to those, who are using sepagoPROFILE and the tech preview of UPM and plan to upgrade. I will call those profiles UPM V1 profiles throughout the article, while UPM V2 profiles will denote the profiles of the official release version.
sepago adresses this issue with the release of Migration Tool for User Profile Manager. This utility takes existing sepagoPROFILE and UPM v1 profiles on the server and migrates them to UPM V2 profiles. Migration Tool changes the folder structure, unpacks compressed data and merges the no longer used mandatory base profile with the per-user settings. This can be done for an arbitrary number of profiles. In this article I’ll provide a simple how-to on migrating from earlier profile versions to UPM profiles.
Basic migration scenario
There are certain requirements for Migration Tool that must be fulfilled to migrate the profiles successfully. The program must be run by a user with administrative rights. The users are selected from Active Directory. The profiles must not be used at the moment and the release version of UPM must be used after the migration.
Let me walk through a simple migration process from UPM V1 profiles to UPM V2. After starting Migration Tool we set the path to the mandatory profile first. This goes into Source Path Mandatory Profile. You can use the button on the right side of the box to select the folder in a dialog. Next we need the path to the UPM v1 profiles that we want to convert. Click the New button in the box named Path to UPM Version 1 profiles and either type in the path or select it in a dialog. If all profiles are stored in one directory, it is a good idea to enter this directory and keep the Adding user names to the directory box checked. Through this the selected user names will be appended to the profiles path using the user’s AD attribute #samAccountName#. The other option is to uncheck this box and enter the profile path including AD attributes to append the user’s profile folder name. All of the user’s AD attributes are supported here. After that we need to adjust the Relative source path to user files (UPM V1), if that is necessary. The default value here is set according to the default installation. If this path inside the user store differs in your installation, change it to match your configuration. Now we need to add the users, whose profiles shall be converted. To do so, simply click the User add button in upper right part of main window. The selection dialog is a standard Active Directory user selection dialog, allowing you to add single users or whole groups.
The basic configuration is set up now and the migration can be started. Click Start conversion and watch the output window for any errors. If the migration completed successfully, the converted profiles can be found in the subdirectory UPM_Profile in the path set in Path to UPM Version 1 profiles. This directory now holds the profiles that can be used with UPM V2.
Advanced migration options
As you have probably noticed there are several other switches to configure the migration process. I will explain them in the following section.
sepagoMigration allows the usage of user’s AD attributes in directory specifications. During the migration the attribute is evaluated and replaced with the value in the AD user object. A common application would be the #samAccountName# attribute to specify the user’s profile directory.
The Target path to user files (UPM V2) setting allows you to modify the output directory below the current profile path. The default output directory is UPM_Profile, any relative path entered here will contain the UPM_Profile directory after conversion. E.g. enter MigrationTest\Test1 to output the converted profile to \MigrationTest\Test1\UPM_Profile relative to the profile directory. It is also possible to enter absolute paths here.
The If target file exists option lets you decide what to do in case of an already existing ntuser.dat in the target directory. Accept changed data merges the data in the existing file with the converted profile data. It overwrites existing keys and values with those from the converted profile. Other options are to delete the file, skip the user or query the action for each user, where the file already exists. To backup any data before changing it, check the Save target file before overwriting/deleting box.
To exclude any registry keys in the user’s registry hive from the migration, enter the path relative to HKCU into the Registry exclusion list box. As a counterpart you can include specific registry keys via the Registry inclusion list box. During the migration only the specified keys will be transferred to the converted profile.
You can use the Directories to exclude and Files to exclude boxes to exclude objects in the file system. To exclude single files or directories from the migration, simply enter them into the list boxes. Please note though that excluded directories will be created, but left empty.
Additionally Migration Tool offers to save and load your configurations including all paths and settings as well as the user list. To provide information about the migration process you can check the log file with the open logfile button.
Meeting the security recommendations by Microsoft
The design of Migration Tool requires specific access rights on all user directories. While this doesn’t affect the usage of the profile directories, it is not compliant to the Security Recommendations for Roaming User Profiles Folders. In detail the owner of the newly created UPM_Profile directory is the administrator running Migration Tool. According to the recommendations it should be the user. If you need to change this, you can use another powerful tool to modify the ownership on the profile directories to match the recommendations. The right tool for this task is SetACL by Helge Klein.
The command line that does the trick for one user profile:
setacl -on “d:\data\profiles\user1\UPM_Profile” -ot file -actn setowner -ownr n:domain\user1 -rec cont_obj
You can incorporate this call to SetACL into a batch file to set the ownership on all profile directories.
An example for setting the owner:
for /f “usebackq” %i in (`dir /b \\server\profiles`) do setacl -on “\\server\profiles\%i” -ot file -actn setowner -ownr n:domain\%i -rec cont_obj
An example for setting the permissions:
for /f “usebackq” %i in (`dir /b \\server\profiles`) do setacl -on “\\server\profiles\%i” -ot file -actn ace -ace “n:domain\%i;p:full”
This concludes the how-to on migration of UPM V1 profiles to UPM V2. The attached pictures show the profile storage on the server and the migration settings from the simple example in this article.
Migration Tool example, server folder structure
Migration Tool simple example
Great info! But where do you download the tool? No link in this article, no info on where to find it when I log into My Citrix. So what’s the deal?
Hi Chris,
the download link is in the box right above the article in the download tab.
You may need to activate JavaScript to see the box.
If this doesn’t work for you, here’s the direct link to the download:
I hope this helps,
Holger