Profile Management architecture
This article describes the folder structure of the user store and of the cross-platform settings store. The user store is the central location for Citrix® user profiles. The cross-platform settings store is a separate location.
Important information about Profile Management stores
The structures of the user store and cross-platform settings store are described here for information purposes and to assist with localizing and troubleshooting. Follow these important recommendations, which are designed to minimize problems with profile data and maintain security:
- Do not change the structure of either store.
- Do not write files and folders directly to any part of a store. The user store is different in this respect from any redirected folders.
- Keep the user store separate from any redirected folders. You can keep them on disjoint shares of the same file server or DFS namespace, for example \\server1\profiles\%username% and \\server1\folders\%username%. This technique also makes it much easier to support Version 1 and Version 2 profiles together, and to support a single set of redirected folders shared by both profile versions.
- Users do not need to see the user store, so do not map a drive letter to it.
- Do not impose quotas on the user store. If you restrict profile size, consider excluding items rather than using a quota.
Folder structure of the user store
The user store defaults to the WINDOWS folder in the user’s home directory. This simplifies pilot installations, but for production systems, configure the user store to be a network share or (for best scalability) a DFS namespace. Supported configurations for enterprise-ready user stores are described in High availability and disaster recovery with Profile Management.
Recommendations on creating secure user stores are available in the article called Create a file share for roaming user profiles on the Microsoft TechNet website. These minimum recommendations ensure a high level of security for basic operation. Also, when configuring access to the user store, include the Administrators group, which is required to modify or remove a Citrix user profile.
Note: On Windows 7 and Windows 2008 R2 client devices, do not select the Encrypt data access check box while creating the share on Windows 2012 R2 File Server.
The folder structure of the user store at the root level is shown in this table.
| Folder | Notes |
|---|---|
| \ | The root of a profile in the user store. |
| \UPM_Profile | This folder contains files and folders from the profile. |
| \UPM_Drive_C | This folder contains any included items from outside the profile (in this case from drive C). This folder is present during upgrades from Profile Management 4.x or earlier. Managing items outside the profile is not supported in Profile Management 5.0. |
| \Pending | This folder contains the lock file, any pending files, and the stamp file if the streaming feature is in use. |
Some examples are shown in this table.
| Example Folder Name | Notes |
|---|---|
| \UPM_Profile\Data | The synchronized content of the Data folder in the user profile. |
| \UPM_Profile\AppData_upm_var | The synchronized content of the de-localized Application Data folder in the user profile. This folder is present during upgrades from Profile Management 4.x or earlier. Managing Version 1 profiles (of which Application Data is an example folder) is not supported in Profile Management 5.0. |
Pending area
The user store includes the pending area. This area is a holding area used by the streamed user profiles and active write back features. All files are synchronized from the pending area to the user store after a user logs off from their last session. New sessions download files from both the user store and the pending area, so the user always experiences an up-to-date profile.
If a server becomes unresponsive, a timeout can be set that releases files in the pending area back to the user store (if configured as part of the streamed user profiles feature).
Folder structure of the user store with multiple platforms
When using the cross-platform settings feature, multiple platforms are involved. You must define platform-specific folders to separate the profiles for each platform. Typically, you do this using Profile Management variables in the Path to user store policy (for example, using %USERNAME%\!CTX_OSNAME!!CTX_OSBITNESS! in the path).
The cross-platform settings store holds the settings for supported applications after the cross-platform settings feature is configured. You specify the name and location of the store during configuration (using the Path to cross-platform settings store policy). The store holds the subset of the user’s settings that roam between operating systems.
For example, you might want to roam settings between Windows XP and Windows 7. The platform-specific folders contain the user settings that are unique to Windows XP and Windows 7. The cross-platform settings store contains the subset of the settings that roam between these operating systems. At logon, this subset is copied into, and remains part of, the platform-specific folders. At logoff, any changes to the subset are extracted and placed back into the cross-platform settings store.
Each platform-specific folder contains standard subfolders (for example, UPM_Profile). For more information, see Folder structure of the user store. In addition, the UPM_CPS_Metadata subfolder is present. This system-created folder contains temporary settings that are shared across operating systems.
The user store and AD forests
Citrix user profiles cannot be managed across forests. They can be managed across domains in the same forest allowing multiple users with the same logon name to access the same resources in the forest. This involves uniquely identifying profiles with the %USERDOMAIN% and %USERNAME% variables in the path to the user store.
However, in this case you must use variables to disambiguate identical logon names when setting the path to the user store. To do this, append the domain name variable to the path. You must also set permissions on the user store and enable Profile Management’s Processed Groups setting using Active Directory’s Universal Groups.
You can use a manually defined system variable such as %ProfVer% to set the operating system version. Or you can use a Profile Management variable to set the operating system name, bitness, or the profile version. For examples of user store paths in AD forests, see Specify the path to the user store.
User store localization
The following table provides an overview of how Profile Management localizes and de-localizes folders when profile data is moved to and from the user store. Only folder names are localized and de-localized. For example, Start menu entries and registry settings are not translated into the correct language by Profile Management.
This information is relevant only when upgrading from Profile Management 4.x or earlier, when Version 1 profiles might be present. Managing Version 1 profiles is not supported in Profile Management 5.0.
| Version 1 English folder | User store folder |
|---|---|
| Accessibility | Accessibility_upm_var |
| Accessories | Accessories_upm_var |
| Administrative Tools | AdminTools_upm_var |
| Application Data | AppData_upm_var |
| Cookies | Cookies_upm_var |
| Desktop | Desktop_upm_var |
| Entertainment | Entertainment_upm_var |
| Favorites | Favorites_upm_var |
| History | History_upm_var |
| Links | Links_upm_var |
| Local Settings | LocalSettings_upm_var |
| My Documents | MyDocuments_upm_var |
| My Music | MyMusic_upm_var |
| My Pictures | MyPictures_upm_var |
| My Videos | MyVideos_upm_var |
| NetHood | NetHood_upm_var |
| PrintHood | PrintHood_upm_var |
| Programs | Programs_upm_var |
| Recent | Recent_upm_vars |
| Start Menu | StartMenu_upm_var |
| Templates | Templates_upm_var |
| Temporary Internet Files | TemporaryInternetFiles_upm_var |
| SendTo | SendTo_upm_var |
| Startup | Startup_upm_var |
| System Tools | SystemTools_upm_var |
Profile container (VHDX) architecture
Profile Management supports two storage models: file-based and container-based. The following sections describe the container-based (VHDX) model.
File-based store versus container-based store
In the file-based model, the profile is copied from the user store to the local machine at logon and copied back at logoff. In the profile container-based model, the profile resides in a VHDX virtual disk that is attached at logon and accessed in place without a bulk copy. The user’s live profile folder becomes a directory junction into the mounted disk.
Container types and VHDX files
Profile Management supports multiple container types. Each type is gated by its own policy, so not every deployment includes all of them.
| Container | VHDX file(s) | Enabled by |
|---|---|---|
| Full profile container | ProfileContainer.vhdx (plus ProfileContainer_RW.vhdx and ProfileContainer_RO.vhdx for differencing disks) | Profile container policy |
| OneDrive container | OneDrive.vhdx (plus indexed or differencing children OneDrive_N.vhdx) | OneDrive container policy |
| App access container | Shared parent disk, volume label AppRepoContainer | App-access container feature |
| Mirror-folder acceleration | MirrorFolders.vhdx | Folder-mirroring acceleration |
| Shared-file (deduplication) store | SharedFile.vhdx, volume label DeduplicationVolume | File deduplication |
The volume label for the full profile container is the user’s sAMAccountName plus a -Profile suffix. The OneDrive container uses -OneDrive and the mirror-folder container uses -MirrFldrs, making each user’s disk identifiable when inspected.
User store paths for container files
Container VHDX files are stored in the user store at the following paths:
Full profile container: <user store>\ProfileContainer\<OS-short-name>\ProfileContainer.vhdx
OneDrive container: <user store>\OneDrive\OneDrive.vhdx
Mirror-folder: <user store>\MirrorFolders\MirrorFolders.vhdx
<!--NeedCopy-->
<OS-short-name> is the short OS identifier (for example, Windows 2022 or Windows 11) that corresponds to the !CTX_OSNAME! variable used by file-based paths; it keeps profiles for different OS versions separate.
Folder layout inside a profile container
The VHDX attaches as a volume GUID path without a drive letter. The per-user mount path is recorded in the registry at:
HKLM\Software\Citrix\UserProfileManager\<SID> value: ProfileContainerVolumePath
<!--NeedCopy-->
The user’s local profile directory is junctioned to the Profiles folder inside the disk. The container volume contains the following folders:
| Folder | Purpose |
|---|---|
| Profiles | Roamed Windows profile tree (NTUSER.DAT and UsrClass.dat live here). This is the junction target, equivalent to UPM_Profile in file-based mode. |
| SyncIncludeProfiles | Staging root for profile include rules |
| SyncIncludeFiles | Staging root for file include rules |
| SyncIncludeDirs | Staging root for folder include rules |
| ResetProfile | Marker file used by the profile-reset feature |
How file-based concepts map to container mode
| File-based concept | Container equivalent |
|---|---|
| UPM_Profile (copied profile contents) | The Profiles folder inside the VHDX, reached through a junction. No data is copied in or out. |
| Pending (streamed or active write-back holding area) | A separate PendingArea.vhdx with read-only and read-write volume handles. No Pending folder exists on the share in container mode. |
| UPM_Drive_C (legacy streamed full tree) | Not used. The full profile is the ProfileContainer.vhdx disk, with SyncInclude staging roots replacing the per-drive folders. |
| Per-OS variable !CTX_OSNAME!!CTX_OSBITNESS! | Preserved as the per-OS ProfileContainer store subfolder |