App Layering – Enterprise Layer Manager (ELM) 2107

Last Modified: Aug 20, 2021 @ 5:47 am


These App Layering pages focus on VMware vSphere as the hypervisor. For Hyper-V, see Citrix App Layering by George Spiers. For Azure, see How to configure Citrix Cloud – App Layering 4.8 to deliver virtualized apps and Office 365 caching – User Layers for XenApp and XenDesktop Service Cloud Workspaces in Microsoft Azure by Christiaan Brinkhoff.

Change Log


From Citrix Blog Post A Breakdown of Citrix App Layering Features by Edition: Citrix App Layering is available in all Citrix Virtual Apps and Desktops (CVAD) editions. This means that you can do the following across any number of Citrix Virtual Apps and Desktops (CVAD) sites in your environment:

  • Create an unlimited number of OS, platform and application layers
  • Create an unlimited number of layered images
  • Create an unlimited number of elastic layers

Citrix Virtual Apps and Desktops (CVAD) Premium Edition customers also benefit from:

  • Multiple hypervisors and/or cloud connections (e.g. Citrix Hypervisor and Azure or Citrix Hypervisor and Hyper-V).
    • Non-Premium sites are limited to one hypervisor or cloud connection type.
  • Multiple provisioning mechanisms (e.g. Machine Creation Services and Citrix Provisioning).
    • Non-Premium sites must select MCS or CPV and use it exclusively with Citrix App Layering.
  • Multiple broker types/platforms (e.g. Citrix Virtual Apps and Desktops (CVAD) with VMware Horizon View).
    • Non-Premium sites can only use App Layering within their Citrix Virtual Apps and Desktops (CVAD) sites
  • User Layers

For Citrix Cloud – Those customers using the Citrix Virtual Apps and Desktops (CVAD) Service are entitled to Premium-level features including all Citrix App Layering capabilities.

Upgrade Enterprise Layer Manager

If you are deploying a new ELM appliance, skip to Import Enterprise Layer Manager.

Supported upgrade paths are:

To upgrade:

  1. When you login to the ELM, you might see a notification about Version 21.7.0 (2107) is now available. Click Start Upgrade.
  2. If you don’t see the upgrade notification, then download it manually:
    1. Download the upgrade package from Citrix App Layering 2107 at Citrix Downloads. Look for the section named For an existing deployment, download the upgrade package. If you are upgrading from 1911 or older, then this might be your only option.
    2. In the App Layering file share, create an Upgrade folder.
    3. Unzip the Upgrade Package, and copy the citrix_app_layering_upgrade_pkg_21.7.0.vhd file to the Upgrade folder in the App Layering file share.
    4. Login to the App Layering ELM management console.
    5. Switch to the System tab > Manage Appliance tab.
    6. On the right, click Upgrade.
    7. In the Upgrade Disk Details page, click Browse.
    8. Expand the Upgrade folder, select the citrix_app_layering_upgrade_pkg_21.7.0.vhd file, and click Choose.
  3. Click the down arrow (next).
  4. In the Confirm and Complete page, click Upgrade.
  5. The browser window changes to the upgrade progress page.
  6. It will eventually say that Upgrade Status is Complete. Refresh the browser.
  7. Login to the App Layering console.
  8. You might immediately see the upgrade notification. Click OK.
  9. Or, you might see some additional prompts:
    1. If the Citrix License Agreement window is displayed, check the box next to I accept the Terms and Conditions, and click Close.
    2. If the Setup Login Credentials wizard is displayed, in the About Your Credentials page, click the down arrow (next).
    3. In the Change Passwords page, enter passwords for the three accounts, and click the down arrow.
    4. In the Confirm and Complete page, click Change Credentials.
    5. Click OK when prompted that the passwords were changed successfully.
    6. Click OK when prompted that the ELM was upgraded.
  10. In the top right of the window, click About.
  11. Verify the ELM Software Version is

Offload Compositing

If you upgraded from a version older than 1911, then enable Offload Compositing on your existing Connectors.

  1. Login to ELM.
  2. Go to System > Connectors.
  3. Right-click a Connector and click Edit Connector Config.
  4. Scroll down and check the box next to Offload Compositing.
  5. Click Save.

Upgrade OS Layer

  1. From Gunther Anderson: You do not uninstall or upgrade the Unidesk Image Preparation Tool – Setup_x64.exe. The current drivers are installed in the ELM, and every time the ELM produces an image for any purpose, it injects the current drivers into it. You do not need to touch your OS layer for that. But you should re-publish all images.
  2. In a new OS Layer version, you should download and run citrix_app_layering_os_machine_tools_21.7.0.exe to allow it to upgrade your system scripts, but you don’t need to do anything beyond that. For Office 2019, your Machine Tools scripts must be version 1905 or later.
  3. When Yes when prompted that the tools will be extracted into C:\Windows\Setup\Scripts.
  4. Replace the existing files. This is especially important for fixing Office activation issues.
  5. If you look on the taskbar, you might see an open program called Set KMS Version.
  6. Click Use KMS.
  7. Then close the window.
  8. To fix Office activation issues, you’ll also need to create a new version of your Office layer, rerun the optimization tool, and then publish the updated image. More details at Office MAK licensing issues at Citrix Discussions.
  9. If Elastic Layers is enabled, then re-publish your images so ELM can inject the new Elastic Layer (and User Layer) driver.

Upgrade Provisioning Services Agent

  1. If you recently upgraded Provisioning Services server, then you might have to re-register the PVS snap-in:
    "C:\Windows\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe" "c:\program files\citrix\provisioning services console\Citrix.PVS.snapin.dll"
  2. On your Provisioning Services server, open Programs and Features. If it says Citrix App Layering Agent, there’s no need to uninstall.

    1. If it says Unidesk Agent, then uninstall it before upgrading.
  3. Go to the Citrix App Layering 2107 files, and run citrix_app_layering_agent_installer.exe.
  4. If upgrading from Agent 4.2 or newer, click Yes to upgrade the agent.
  5. In the Welcome to the InstallShield Wizard for Citrix App Layering Agent page, click Next.
  6. In the InstallShield Wizard Completed page, click Finish.
  7. Programs and Features shows the installed Agent version as 21.700.5.

Import Enterprise Layer Manager Appliance

This section is for new installs.

App Layering 4.x availability and recovery concepts guide:

  • Layered images, Elastic Layers, and User Layers do not communicate with ELM, so ELM’s availability is not a concern.
    • Do not change the vCPUs or memory allocated to the ELM appliance.
  • All created layers are stored on the ELM appliance. Simply backup the appliance.
    • Layers can be exported from the ELM appliance to a file share and optionally imported to another ELM appliance.
  • Elastic Layers and User Layers are always-open VHD files stored on a file share(s) that is separate from the ELM.
    • The file share(s) should be highly available. Use a clustering technology (e.g. Scale Out File Server) that supports always-open VHD files.
    • It’s not necessary to backup Elastic Layers, but you might want to replicate them to a different datacenter for multi-datacenter access. Make sure the replication tool supports always-open VHD files.
    • User Layers should be backed up and/or replicated. Use a backup method that supports always-open VHD files.

Download Appliance

  1. You can download App Layering 2107 Appliance Installation Package from Citrix Downloads.
  2. After downloading, extract the 2107 .zip file.

Import ELM Appliance

To import the ELM appliance:

  1. In vSphere Web Client, right-click a cluster, and click Deploy OVF Template.
  2. In the Select an OVF template page, browse to the vmware_21.7.0.6.ova file, and click Next.
  3. In the Select name and location page, give the machine a name, and click Next.
  4. In the Select a compute resource page, select a cluster, and click Next.
  5. In the Review details page, click Next.
  6. In the Accept license agreements page, click Accept, and then click Next.
  7. In the Select storage page, select a datastore. The ELM appliance stores all master layers inside the appliance, so ensure there’s sufficient disk space (typically 300-500 GB) for the virtual appliance.
    1. You can view the appliance’s consumed disk space inside the ELM Management Console at System > Manage Appliance.
    2. To expand the storage, either increase the existing disk size, or add a disk to the VM. Then, on the right, is a link to Expand Storage.
  8. Select thin provision, or not. Then click Next.
  9. In the Select networks page, click Next.
  10. In the Ready to complete page, click Finish.
  11. See Firewall ports at Citrix Docs.

Configure ELM IP Address

  1. Once imported, power on the ELM appliance.
  2. After the RUN_ONCE commands are complete, login to the console as administrator with a password of Unidesk1. You might have to press enter before the logon prompt appears.
  3. Enter c to configure networking.
  4. Enter s to assign a static network.
  5. Enter a new IP address for this appliance. Then enter y to save settings and restart networking.
  6. Press <Enter> to continue.
  7. While here, feel free to configure the time zone.
  8. Press / to search. For Central Time, search for chicago, and note the time zone number.
  9. Press Q to quit the display.
  10. Enter the time zone number to configure it.
  11. NTP is configured to use Internet servers. Feel free to change them.


  1. Use Internet Explorer to connect to the ELM IP address. Silverlight does not work in Chrome.
  2. If Silverlight is not installed, click the button to install it.
  3. Uncheck the two boxes, and then click Install now.
  4. Click Close.
  5. When you go to the ELM console, the screen will be white for a few seconds. Be patient.
  6. You can login as administrator with Unidesk1 as the default password.

First Login

  1. The first time you logon you are prompted with the End User License Agreement. Check the box next to I accept the Terms and Conditions, and then click Close.
  2. If the Setup Login Credentials wizard is displayed, in the About Your Credentials page, click the down arrow (next).
  3. In the Change Passwords page, enter passwords for the three accounts, and click the down arrow.
  4. In the Confirm and Complete page, click Change Credentials.
  5. Click OK when prompted that the passwords were changed successfully.
  6. Feel free to close the welcome wizard.

Appliance Certificate

  1. In the ELM Management Console, go to System > Settings and Configuration.
  2. Scroll down until you see the HTTP Certificate Settings section. Click the Edit button.
  3. Scroll down, and click Upload.
  4. Browse to a PEM file that contains an unencrypted RSA key, and one certificate (no chain). You can use OpenSSL to convert a .pfx file to a PEM file.
  5. If you scroll up, it should show you the Common Name of the certificate you uploaded. If it’s the root certificate, then you need to remove the extra certificate from the PEM file.
  6. Scroll down and click Save.
  7. Click Yes to restart the web server.

  8. It might take a few minutes to apply. Eventually, you should be able to point your browser to the https URL and not see any certificate errors.
  9. At System > Settings and Configuration, you can scroll down to the Security Settings section to edit the Management Console idle timeout.

File Share

  1. On a Windows file server, create a new share that will store the Elastic Layers. Only SMB shares are supported with Elastic Layers. NFS shares will not work with Elastic Layers.
  2. For High Availability, you can use any file server High Availability technology like File Server Scale-out Clustering, DFS, etc. For local high availability, Citrix recommends clustering over DFS Replication since DFS failure requires reboot of Elastic Layered Machines. See DFS path and Elastic Layers at Citrix Discussions.
  3. For DR Elastic Layer machines, the registry value HKEY_LOCAL_MACHINE\SOFTWARE\Unidesk\ULayer:RepositoryPath can be configured to point to a file share in a DR site. See DFS path and Elastic Layers at Citrix Discussions, and CTX222107 You can change the Elastic Layer repository in the registry without reimaging (4.x).
  4. Give Everyone (or equivalent) Full Control to the share.
  5. On the Security tab, make sure the Users groups only have Read access (no Modify/Write).
  6. Add a service account to the share, and give it Modify access. ELM uses this service account to upload elastic layers to the share.
  7. Back in the ELM, go to System > Settings and Configuration.
  8. Scroll down until you get to the Network File Shares section. Click Edit.
  9. Make sure Windows share is selected. Elastic Layers don’t work on NFS.
  10. Enter the file share path, the service account credentials.
  11. Click Test Network File Share.
  12. Click Save.

User Layers Storage Locations

ELM 4.14 and newer support User Layers.

File shares for User Layers are configured at System > Storage Locations. The Elastic Layer file share is listed by default. But you can add more Locations. Each Storage Location can be assigned to different user groups. And you can prioritize the Storage Locations. See Add storage locations for User layers at Citrix Docs. And see David Wilkinson Citrix Application Layering – User layers.

For each new Storage Location:

  1. Create a Users folder in the root of each share.
  2. Each Users folder needs permissions that look like the following. CREATOR OWNER needs Full Control. The Users group needs Create Folder/Append Data permission to This folder only.
  3. In ELM, add Storage Locations and assign them to groups.

  4. If users are assigned to multiple Storage Locations, click Prioritize Storage Locations to prioritize the assignment.

  1. Go to Users > Directory Service.
  2. On the right, click Create Directory Junction.
  3. Give the “junction” a friendly name (e.g. domain name).
  4. Enter one domain controller address or LDAP Load balancing VIP.
    • According to CTP George Spiers at Citrix Discussions, instead of entering a single domain controller address, you can enter your domain’s FQDN (domain.local) and it will use DNS to find a domain controller.
    • In this scenario, the SSL certificate check will indicate that the CN (common name) does not match the entered Server Address.
  5. Check the box next to Use SSL. (assuming you have certificates on your domain controllers)
  6. Change the port to 636 if it isn’t already.
  7. Click Test Connection.
  8. When prompted with a certificate error, click OK.
  9. Check the box next to Ignore Certificate Errors, and then click Next.
  10. You’ll need a bind account. Get the full Distinguished Name (look in Active Directory Users & Computers > user > Attribute Editor) and enter it here in the Authentication Details page with the password. Click Test Authentication.
  11. After successful authentication, click the down arrow.
  12. In the Distinguished Name (DN) Details page, click the drop down to select the Base DN. Click Test Base DN. And then click the down arrow.
  13. In the Attribute Mapping page, leave them set to the defaults, and click the down arrow.
  14. In the Confirm and Complete page, click Create Directory Junction.

Role Based Access

  1. Go to Users > Directory.
  2. Search through the tree and find your ELM Admins group. Select it. On the right, click Edit Properties.
  3. In the Machine Association page, click the down arrow.
  4. In the Roles page, change it to Administrator, and click the down arrow.
  5. In the Confirm and Complete page, click Update Group.
  6. Logout of ELM.
  7. Log back in using an AD account that’s in your ELM Admins group.

Citrix Provisioning Publishing Agent

To publish to Citrix Provisioning, you install the App Layering Agent on the Citrix Provisioning Servers. It’s only needed on one Provisioning Server.

The installation of the Agent can be automated. See Dennis Span Citrix App Layering Agent unattended installation.

From Install the App Layering Agent (required for PVS and Connector Scripts) at Citrix Docs.

  1. Ensure the Citrix Provisioning services are running as a domain account. Network Service won’t work.
  2. Run the following command on the PvS 7.7 or newer Server. Note, if you upgrade PvS, you’ll have to run this command again.
    "C:\Windows\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe" "c:\program files\citrix\provisioning services console\Citrix.PVS.snapin.dll"

    1. If Citrix Provisioning 7.6 or newer, then run the following command instead:
      "C:\Windows\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe" "c:\program files\citrix\provisioning services console\MCliPSSnapIn.dll"
  3. Go to the App Layering 2107 files you downloaded from Citrix Downloads, and run citrix_app_layering_agent_installer.exe.
  4. In the Welcome to the InstallShield Wizard for Citrix App Layering Agent page, click Next.
  5. In the License Agreement page, select I accept the terms in the license agreement, and click Next.
  6. In the Agent Port page, click Next.
  7. In the Ready to Install the Program page, click Install.
  8. Enter the ELM FQDN, enter ELM credentials, and click Register.
  9. Registration logs can be found at C:\Program Files (x86)\Citrix\Agent\Logs.
  10. In the InstallShield Wizard Completed page, click Finish.
  11. Programs and Features shows the installed Agent version as 21.700.5.
  12. When an image is published to Provisioning Services, ELM can run a script. Citrix has a sample Versioning and Convert VHD to VHDX script that converts the VHD file to VHDX, and/or adds the published image as a version. The script files can be installed on the PvS server at this time. Later, you specify the path to the script when you create the PvS Connector in ELM while creating an image template.
  13. Citrix also has a BootPrivate script that modifies the vDisk mode to Private, boots the vDisk on a pre-defined target so that it can run pre-defined layer scripts, shuts down the target, waits for that shutdown, and then switches the mode back to standard.

Next Steps

113 thoughts on “App Layering – Enterprise Layer Manager (ELM) 2107”

  1. Issue creating AHV_Connector from Azure -> OnPrem

    OnPrem Hypervisor: Nutanix
    ELM Appliance: Azure

    I am able to authenticate into Nutanix, I select the Template and the Storage Container, and hit Test. And after awhile it fails with Error 502. I’ve exported the ELM Appliance Logs and it says:

    Please check that the ELM is in the container’s ‘white list

    The ELM is in Nutanix’s Filesystem Whitelist.

    I created an Azure NSG and applied it to our Citrix Subnets in Azure that allows:
    Ports 3000,3500,3006,3506,3004,3504,3015,3515,9440,8016,2409

    Still with no luck, I have a case with Citrix open and they’ve acknowledged my configurations stated above.

    1. Any source NAT between ELM and Nutanix? Can you do a network trace or tcpdump on Nutanix to confirm the source IP?

  2. Hi Carl,

    After upgrading from 2005 to 2009 App Layering in Prod I am getting an error message while creating a version to OS Layer “The issuing certificate does not have a usable private key”. FYI – I never made any changes to HTTP certificate settings.

    In Dev App Layering I am getting “Waiting for the Compositing Engine machine to be ready” before the upgrade it used to work fine.

    Can I have your suggestions on this please. Thanks!!

  3. Hi Carl,
    After upgrading to 2009 elastic applications on server VDA works only first time logon. If i logoff and try to logon again the servers hang and i have to hard reboot from hypervisor Vsphere. I have this issue on Windows 2016 and Windows 2019. If i use an image template with 2003 agent layer it works.

    1. we are having similar issues which seem to have started after the upgrade to 2009 and publishing a new template from the appliance. We are getting random server hangs and machines doing unregistered. We are also seeing people with multiple sessions on the same server. DId you manage to resolve the issues with 2009 or did you rollback to 2003?

  4. Hi Carl have you noticed anything strange after the update to 20.8.3, when using pvs i have republish the new image it seam the c: drive has an extra partition added with a extra 20gb?

      1. Hi Carl yes they are attached as separate disks but the c drive is now showing as 20gb in explorer I have checked an old image and it does have the same partition layout for the c drive but the older image would have the correct size in explorer and the ulayeredmage partition would be the partition you would see in mypc now the UdiskP1V0R1 shows and when I’m optimising the image I use the sdelete utility that when I noticed the change

  5. Trying to trial this in a test environment, imported the ova into vsphere, installed silverlight and tried to access via Internet Explorer. I’m presented with the login box but every time I enter the credentials and press the login button I keep getting this error message “The Layering Management Console is having trouble communicating with the Management Service. This issue usually indicates that a service interruption occurred, the service restarted, or the connection was lost.” I have not modified the appliance in anyway after importing it.

  6. Upgrading to ELM 2001 completely broke our Office 2016 Layer. Even when I followed various articles where to open up the OS layer, install the 2001 tools, create a new Office version with this OS layer and then re-run optimizer, kms etc…it still wouldn’t load up properly (“configuring Office”) when installed on a new template. Needless to say I soon reverted back to an earlier ELM snapshot.
    I would be interested to know anybody’s thoughts on this?

  7. Hi Carl,

    Once again a great article. Thank you. we are planning to migrate from UserLayer to UPM to make profiles file based for real time replication. Please a suggest a best way to migrate user data from the UserLayer VHDs to file share.

  8. Hi Carl,

    We imported the OS layer ane when we are taking version with offloading composite enabled on vsphere, we are unable to finalize and close the version. It’s failing all the time..

    Can you help me on this…

Leave a Reply