Deploy user layers

User layers persist each user’s:

  • Profile settings
  • Data
  • Locally installed applications in non-persistent VDI environments

When you enable user layers on an image template, systems provisioned using the resulting layered images provide every user with a user layer.

When a user logs on to a desktop that is user layer-enabled, a new Search index database is created. The index incorporates search information from the user layer and any elastic layers. The Search feature is only available when the indexing is complete.

This topic explains how to enable user layers on an image template, and on the resulting layered images. Systems that you provision using the images provide every user with a user layer.

Types of user layers

You can enable the following types of user layers:

  • Full - All of a user’s data, settings, and locally installed apps are stored on their user layer.
  • Office 365 - (Desktop systems) Only the user’s Outlook data and settings are stored on their user layer.
  • Session Office 365 - (Session hosts) Only the user’s Outlook data and settings are stored on their user layer.

You can enable a Full user layer, an Office 365 user layer, or a Session Office 365 user layer. Full user layer includes everything that Office 365/Session Office 365 user layer saves, along with the settings and data for other applications.

Before you start

Before enabling user layers, be sure to follow the requirements and guidelines in this section.

Requirements

Before enabling user layers, be sure to meet the requirements that apply to the following types of user layers:

  • All types of user layers
  • Full user layers
  • Office 365 and Session Office 365 user layers

All user layers

To enable user layers you need:

  • Adequate network bandwidth. Bandwidth and latency have a significant effect on the user layer. Every write goes across the network.
  • Enough storage space allocated for users’ data, configuration settings, and their locally installed apps. (The appliance uses the main storage location for packaging layers, publishing layered images, and serving up Elastic layers.)

Full user layers

  • When using Profile Management with a Full user layer you must turn off the deletion of the user’s information on logoff. Depending on how you are deploying the settings, you can turn off deletion using either:

    • A Group Policy Object.
    • The policy on the Delivery Controller (DDC).

Office 365 and Session Office 365 user layers

  • You must use a profile manager, such as the Citrix Profile Manager. Otherwise, Outlook assumes that every user who logs in is a new user and creates OS files for them.
  • The Office layer must be included in the image template and deployed in the layered image. However, you can use other Elastic layers with an Office 365 user layer.
  • Microsoft Office is supported as an app layer in a published image only, not as an elastic layer.
  • Any change to the default location of the search index files is not be preserved in the Office 365 layer.
  • This feature has been tested for one desktop per user at a time (Single sign-on).

Compatibility

Full user layers are supported on the following platforms:

  • Operating systems:
    • Windows 7, 64-bit
    • Windows 10, 64-bit
  • Publishing platforms:
    • Citrix Virtual Desktops
    • VMware Horizon View

Applications that are not supported on a user layer

The following applications are not supported on the user layer. Do not install these applications locally:

  • Enterprise applications: Enterprise applications, such as MS Office and Visual Studio, must be installed in app layers. User layers are based on the same technology as elastic layers. As with elastic layers, never use user layers for these enterprise applications!
  • Applications with drivers that use the driver store. Example: a printer driver.

    Note:

    You can make printers available using Group Policies. See GPO-installed printers in the following section.

  • Applications that modify the network stack or hardware. Example: a VPN client.
  • Applications that have boot level drivers. Example: a virus scanner.
  • Applications that require you to add a local user or group. Local users and groups that you add as part of installing an application only persist in the OS layer. Consider installing an application on a layer that will be included in the base image, with the required user or administrator added in the OS layer.

Windows updates

Windows updates must be disabled on the user layer.

Outlook store add-ins

Citrix Profile Management disables Store add-ins.

The first time Outlook starts, the Store/Add-ins icon on the ribbon displays a window with a long list of add-ins. During the initial login, if you install add-ins, they appear on the ribbon on subsequent logins. If you do not install the add-ins, the Store/Add-ins icon displays a blank white window.

GPO-installed printers

For users on non-persistent desktops running Windows 10, you can install printers using a Group Policy. With a policy in place, the printers are listed in users’ Devices and Printers, application printer settings, and device manager.

To set up GPO-installed printers:

  1. Enable user layers in the image template.
  2. Ensure that the desktop is joined to the domain (on the Platform layer).
  3. Create a group policy to deploy each network printer, and then assign it to the machine.
  4. When logged in as a domain user, verify that the printer is listed in Devices and Printers, Notepad, and device manager.

VMware Horizon View

Horizon View must be configured for non-persistent desktops, and the desktop must be set to Refresh at logoff. Delete or refresh the machine on logoff. Example:

localized image

After logging off with View set to Refresh Immediately, the desktop goes into maintenance mode. If there is only one machine in the pool, the pool is not available until that machine has completed the refresh.

  • The first time a user logs on to their desktop, the appliance creates a user layer for them.
  • Users receive their user layers even if their elastically assigned layers do not load.
  • If you rename the user in AD, a new directory and user layer is created for the new name. Change the user’s name in the following places:
    • The directory on the file share.
    • The VHD file on your hypervisor.

User layer location

When an image template has user layers enabled, the images you publish persist users’ data, settings, and locally installed apps.

When user layers are enabled, you must add storage locations for the layers.

Important:

Do not allow user layers to be saved on the appliance’s main file share. Otherwise, space can be depleted for:

  • Upgrading the software.
  • Serving up elastic layers to users.
  • Saving files that you are moving to a hypervisor for which there is no supported connector.

The first storage location added to the appliance becomes the default location for user layers that are not associated with any other storage location. When you add more storage locations, they are listed in priority order.

You can assign groups of users to each storage location that you add.

Where a user layer is stored when the user belongs to more than one group

If a user belongs to more than one group and those groups are assigned to different storage locations, the person’s user layer is stored in the highest priority storage location.

If you change the priority order of the storage locations that the user is assigned to after the person’s user layer was saved to the highest priority location, data saved up until that point remains in the original location. To preserve the person’s user layer, you must copy their user layer to the new highest priority location.

How to specify the user layer file share location on a specific image

You can support a user who needs to access two separate images at the same time, where both images:

  • Need the persistence of user layers.
  • Were created using the same OS layer.

To configure user layer file share assignments:

  1. Add the following Registry key in one or more of your published images before any user logs in:

[HKLM\Software\Unidesk\ULayer] “UserLayerSharePath”

You can add the preceding key to the platform layer, to an app layer, or as a machine group policy.

If you add the UserLayerSharePath key to the image before a user logs in, the appliance ignores the user layer share assignments. Instead, all users on the machine use the specified share for user layer VHDs. The \Users subtree is appended to this key to locate the actual layers.

Where user layers are created on the appliance

On the appliance’s network file share, user layers are created in the Users folder. For example:

\MyServer\\*MyShare*\Users

Each user has their own directory within the Users directory. A user’s directory is named as follows:

Users\\*DomainName_username*\\*OS-Layer-ID-in-hex*_*OS-Layer-name*\\*username*.vhd

For example:

  • User’s login name: jdoe
  • User’s Domain: testdomain1
  • OS layer: MyOSLayer (ID is in hexadecimal format: 123456)
  • User layer would be created in:
\MyServer\MyShare\Users\testdomain1_jdoe\123456_MyOSLayer\jdoe.vhd

Where users can access their user layer

When Full user layers are created, users can access the files in the following directory:

C:\user\\<username\>\Appdata\local

When Office 365 layers are created, the user layers directory is redirected to the Office 365 layer:

C:\user\\<username\>\Appdata\local\Microsoft\Outlook

Add a storage location

To add a storage location for an image’s user layers:

  1. Log into the management console.

  2. Select System > User Layer Storage Locations. A list of file shares is displayed, except for the appliance’s main file share.

  3. Select Add Storage Location, and enter a Name and Network Path for the new location.

  4. On the user layer Assignments tab, expand the directory tree.

  5. Add the new storage location by clicking the check boxes for one or more groups.

  6. A list of file shares is displayed, except for the appliance’s main file share.

  7. On the Confirm and Complete tab, select Add Storage Location.

Once the storage locations are added, you must set security on the user layer folders.

Configure security settings on user layer folders

You can specify more than one storage location for your user layers. For each storage location (including the default location) you need to create a \Users subfolder and secure that location.

The security on each user layer folder must be set to the following values by a domain administrator:

Setting name Value Apply to
Creator Owner Modify Subfolders and Files only
Owner Rights Modify Subfolders and Files only
Users or group: Create Folder/Append Data; Traverse Folder/Execute File;List Folder/Read Data; Read Attributes Selected Folder Only
System Full Control Selected Folder, Subfolders and Files
Domain Admins, and selected Admin group Full Control Selected Folder, Subfolders and Files

To configure security on user layer folders:

  1. Log into the management console.

  2. Click System > User Layer Storage Locations. The file shares displayed are the storage locations defined for user layers. Say you’ve defined three storage locations so that you can manage storage for Group1 and Group2 separate from everyone else in the organization: `
    • Default location - \\MyDefaultShare\UserLayerFolder\
    • Group1 - \\MyGroup1\Share\UserLayerFolder\
    • Group2 - \\MyGroup2\Share\UserLayerFolder\

    Note: The appliance’s main file share, which is used for storing OS, app, and platform layers, is not listed as a user layer storage location.

  3. Create a \Users subdirectory under each file share:
    \\MyDefaultShare\UserLayerFolder\Users\

    \\MyGroup1Share\UserLayerFolder\Users\

    \\MyGroup2Share\UserLayerFolder\Users\
  1. Apply the preceding list of security settings to each subdirectory under \Users.

Move existing user layers to the new storage location

Copy each user layer storage location to its new location:

  1. Ensure that the user layer is not in use.

    If a user logs in before you move their user layer, a new user layer is created. No data is lost, but if it happens, be sure to:

    • Move the newly created user layer to the new directory.
    • Preserve the user’s ACLs.
  2. Browse to the directory containing the user layer VHD file.

  3. Using the following command, copy each of the user layer VHD files from the previous location to the new one

    xcopy Domain1\User1 Domain1_User1\ /O /X /E /H /K
  1. Verify that all permissions are correct on the following directories, and files within them:
    \\\Root\Engineering\Users

    \\\Root\Engineering\Users\Domain1_User1\\...

    \\\Root\Engineering\Users\Domain2_User2\\...

If you let users create user layers

If you choose to let users create user layers, you must manually clean up the original directories and files from your share.

Set the user layer size

The user layer size is set to a maximum of 10 GB by default. You can change the maximum size, however, by defining a quota for the user layer share. If a quota is defined, the user layer is configured to be a maximum of that size.

When using Office 365 user layers, the Outlook layer defaults to 10 GB, but Outlook sets the volume size based on the amount of free disk space and may use more or less space based on what is available on the layered image. The size reported is based on the layered image.

Set a quota

You can set a hard quota on the user layer size using either of Microsoft’s quota tools: File Server Resource Manager (FSRM) or Quota Manager.

The quota must be set on the user layer directory, named Users.

Note:

Changing the quota (increasing or decreasing) only impacts new user layers. The maximum size of existing user layers was previously set and remain unchanged when the quota is updated.

Max size registry overrides

It is possible to over-ride the default user layer max size, using the registry on managed machines. The following registry keys are optional. You do not have to configure these keys for normal operation. If you need one of these keys, add it manually using a layer or a GPO/GPP.

Registry Root: HKLM\Software\Unidesk\Ulayer

Key Type Default Value Description
UseQuotaIfAvailable String True; False True to enable discovery and use of quotas. False to disable.
DefaultUserLayerSizeInGb DWord User defined The size of the user layer in GB (for example 5, 10, 23, …) When not specified the default is 10.
QuotaQuerySleepMS DWord User defined The number of milliseconds to wait after creating the directory for the user layer before checking to see if it has a quota. This is necessary to give some quota systems time to apply the quota to the new directory (FSRM requires this). When not specified the default is 1000

Customize user layer notification messages

When a user is unable to access their user layer, they receive a notification message.

User layer messages

User layer notification messages include the following. You can customize the first two of the messages, using the steps listed below.

  • User Layer In Use (customizable message)

    We were unable to attach your user layer because it is in use. Any changes you make to application settings or data will not be saved. Be sure to save any work to a shared network location.

  • User Layer Unavailable (customizable message)

    We were unable to attach your user layer. Any changes you make to application settings or data will not be saved. Be sure to save any work to a shared network location.

  • System not reset after user sign-out

    This system was not shut down properly. Please log off immediately and contact your system administrator.

How to customize a message

You can customize notification messages as follows. Messages you enter can be in any language.

  1. Log into the management console as administrator.
  2. If you want to create a new location, click Add Storage Location.
  3. If you want to customize messages for an existing location, click Edit Storage Location.
  4. In the Add/Edit Storage Location wizard, click the user layer Messages tab and the Override check box.
  5. Enter the messages exactly as you want them to be displayed.
  6. Use the Confirm and Complete tab to save your changes.

Repair a user layer

The user layer repair feature lets you remove an app and its files from a person’s user layer. You can use this feature after delivering an app to users who have already installed the app locally on their user layer. The repair feature removes conflicting files whether you deliver the new app layer as part of the base image or as an elastic layer.

  • Example 1: You create an app layer that includes the file, you.txt, and provide the app layer elastically to users. When a user changes the file, the changes are stored in their user layer. If their changes break the app, or the file was corrupted, the user layer repair feature lets you clean up the problem file by removing it from the user layer. The user then sees the file that is provided elastically as part of the app layer.

  • Example 2: A user deletes an app that is assigned to them elastically. Because user layer takes precedence, once the user’s local copy of the app is deleted, the user no longer sees that version of the app. The user sees the app layer that is assigned as an elastic layer.

  • Example 3: A user installs an application locally, and some time later the administrator creates an app layer for the same application. The user layer repair feature removes any conflicting files installed by the app from the user layer so that the user then sees the version supplied in the app layer.

How user layer repair works

The appliance generates user layer repair JSON files that you can use to clean up or restore the user layer. You manually copy the JSON files to the user layers that need the repair.

If the repair upload folders do not exist on the network share they are created automatically. The appliance writes the repair JSON files to the following directories on the File share:

<StorageLocationShare>\Unidesk\Layers\App\Repair\
<StorageLocationShare>\Unidesk\Layers\App\PackageAppRules

The Repair directory contains the JSON files for each version of each layer that the appliance knows about. Whenever you finalize a new app layer or a version of it, the appliance generates and uploads the repair files.

The repair files for each layer include:

UserLayerRepair_LayerIdInDecimal_RevisionIdInDecimal.json
UserLayerRepair_<layer id>_<layer version>.json

To see the layer ID in the console, click the Layer tab, select the layer, and click the “i” icon. The layer ID is displayed along with other layer details.

The PackageAppRules directory contains the package app rules for each version of a user layer.

How long does it take to repair a layer?

The repair process time varies based on how large the layer is and how many objects need to be deleted.

A repair of a layer that needs to be mounted but has no actual operations to perform adds about 5 seconds to the login process. This reduces to 2 seconds when the app layer is included in the image.

The additional time beyond this will vary depending on the operations, but for a typical app layer it is less than 10 seconds, so 12 to 15 in total.

Repair a user layer

To repair the user layer for a user:

  1. Identify the version of an app layer that needs to be repaired.

    • If there are multiple layer repairs, you can copy all of the available uploaded repair JSON files to the version of the user’s user layer that needs repairing.
  2. Locate the pre-generated UserLayerRepair files. If the files have not been generated, contact App Layering Support. Your Support engineer can generate the repair files manually for you.

  3. Copy the user layer repair files directly to the user’s VHD location. The next time the user logs on, a repair operation occurs.

    If the user layer repair task completes, the UserLayerRepair.JSON file is removed.

    Note:

    If a JSON Rules file exists on the share and has been modified by the user, it is not overwritten. This allows users to modify those files if they want to.

Log files for user layer repairs

The log file, ulayersvc.log, contains the output of the user layer repair executable.

C:\ProgramData\Unidesk\Logs\ulayersvc.log

Any changes made during the cleanup are logged there, along with any other changes that the service logs.

What happens if a repair fails?

In the event of a failure, the user receives a message that the repair has failed, and that they should contact their admin. You can configure the message in the same place as the other storage location messages.

A repair failure can occur in the following cases:

  • Bad UserLayerRepair.json formatting (very unlikely, since the JSON files are generated).
  • Cannot find a specified app layer’s .VHD or in-image package_app_rules file.
  • Failure to attach an app layer’s VHD file.
  • Unexpected (random) exceptions interrupting the repair process.

If any of these issues occur, the UserLayerRepair.JSON file is NOT removed, and processing of remaining JSON files stops.

To identify the exact reasons for the failure, review the user’s ulayersvc.log file. You can then allow the repair to run again on subsequent logons. Assuming the cause of the failures is resolved, the repair eventually succeeds, and the UserLayerRepair.JSON files are removed.