App Layering – Enterprise Layer Manager (ELM) 2403

Last Modified: Mar 27, 2024 @ 1:08 pm


These App Layering pages focus on VMware vSphere as the hypervisor.

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 and all Citrix DaaS (Citrix Cloud) 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 and all Citrix DaaS customers (Citrix Cloud) 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.

See Citrix Docs for supported upgrade paths:

ELM 2204 is the last version to support Silverlight, since Silverlight has been removed from ELM 2206 and newer.

To upgrade:

  1. When you login to the ELM using HTML5, if you click your user menu on the top right, then you might see Upgrade Appliance with an alert next to it. If you don’t see it yet, then you might have to wait for the Download task to complete.

  2. If you don’t see the upgrade notification, then download it manually:
    1. Download the upgrade package from Citrix App Layering 2403 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_24.3.0.vhd file to the Upgrade folder in the App Layering file share.
    4. Click your name on the top right and then click Upgrade Appliance.
    5. If the field is not already populated, then click Browse.
    6. Browse the file share, select the upgrade disk, and then click Save.

    7. Click Confirm and Complete.
    8. In the Confirm Upgrade page, click Upgrade.

    9. Wait for the upgrade to complete.
    10. Then click Return to login and login.
    11. Click Dismiss acknowledging that connector caches have some items removed.
    12. On the top right, click your username and then click About to see the current version, which should be 24.3.

Offload Compositing

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

  1. Login to ELM.
  2. If HTML5 interface, go to Connectors. If Internet Explorer, then go to System > Connectors.
  3. If HTML5 interface, highlight a connector and click Edit. If Internet Explorer, right-click a Connector and click Edit Connector Config.

  4. Scroll down and check the box next to Offload Compositing. Version 2304 and newer have a new interface for VMware Connectors.

  5. Click Confirm and Complete or Save.

Upgrade OS Layer

  1. From Gunther Anderson at Citrix: You do not uninstall or upgrade the Citrix App Layering Image Preparation Utility – 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_24.3.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. Re-publish your images so ELM can inject the new drivers.

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. Go to the Citrix App Layering 2403 files and run citrix_app_layering_agent_installer.exe.
  3. Click Yes to upgrade the agent.
  4. In the Welcome to the InstallShield Wizard for Citrix App Layering Agent page, click Next.
  5. In the InstallShield Wizard Completed page, click Finish.

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 2403 Appliance Installation Package from Citrix Downloads.
  2. After downloading, extract the 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_24.3.0.2.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 > Monitoring and Storage, or 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 a datastore, 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. Open the virtual machine console.
  3. 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.
  4. Enter c to configure networking.
  5. Enter s to assign a static network.
  6. Enter a new IP address for this appliance. Then enter y to save settings and restart networking.
  7. Press <Enter> to continue.
  8. While here, feel free to configure the time zone.
  9. Press / to search. For Central Time, search for chicago, and note the time zone number.
  10. Press Q to quit the display.
  11. Enter the time zone number to configure it.
  12. NTP is configured to use Internet servers. Feel free to change them.


In App Layering 2206 and newer, the Silverlight interface has been removed. This section is only for App Layering 2204 and older, which require Silverlight for some or all features.

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

First Login

  1. In App Layering 2206 and newer, use Edge or Chrome to connect to the ELM. In App Layering 2204 and older, use Internet Explorer to connect to the ELM. Login using administrator and Unidesk1.
  2. The first time you logon, you are prompted to accept the End User License Agreement.

  3. Then you are prompted to set three passwords.

  4. You then see the Get Started wizard.

Appliance Certificate

  1. In the HTML5 console, go to System > HTTP Certificate Settings.

    1. In the Internet Explorer Console, go to System > Settings and Configuration.
    2. Scroll down until you see the HTTP Certificate Settings section. Click the Edit button.
  2. In HTML5 console, on the right, click Upload to replace the default management certificate.

    1. In Internet Explorer,  scroll down and click Upload.
  3. 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.
  4. Make sure it says that the web server will restart, which means that it’s a valid certificate.

    1. In Internet Explorer, 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.
    2. Scroll down and click Save.
    3. Click Yes to restart the web server.

  5. 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.
  6. In HTML5 console, at System > Security and Retention Settings, you can change the management console timeout.

    • In Internet Explorer console, 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.
    1. Elastic Layers are always-open VHDX files that can’t be replicated using DFS. For HA, build a File Server cluster, like Microsoft Scale Out File Server.,that supports SMB3 Continuous Availability.
  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 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. In App Layering 2206 and newer, in Chrome or Edge, go to System and then Network File Share.

    1. On the top right, click Edit.
    2. Enter the path and service account credentials. Click Confirm and Complete.
    3. Click Save.
  8. In App Layering 2204 and older, in the Internet Explorer console, go to System > Settings and Configuration.

    1. Scroll down until you get to the Network File Shares section. Click Edit.
    2. Make sure Windows share is selected. Elastic Layers don’t work on NFS.
    3. Enter the file share path, the service account credentials.
      1. Citrix CTX227613 App Layering: Supporting DFS File Shares: The ELM can only access a DFS namespace if SMB 1.0 is enabled on the servers.
    4. Click Test Network File Share.
    5. Click Save.

In App Layering 2204 and older, you must use the Silverlight interface. Newer versions of App Layering can use Chrome/Edge.

  1. Go to System > Directory Services.
  2. Click Add Directory Junction.
  3. Enter the address of a domain controller 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.
  4. . Enter bind account credentials. Click Connect.
  5. Click Accept and Continue.
  6. For Specify start point, click the field and select the Base Distinguished Name.
  7. Give the directory junction a friendly name. Then click Confirm and Complete.

Role Based Access

This is configurable in the HTML5 interface in Citrix App Layering 2204 and newer.

  1. On the left, click System. In the middle, click Administrators. On the right, on the Directory Administrators tab, click Add Administrators.
  2. Click Add Accounts.
  3. Search for the new admin group, check the box next to it, and click Save.
  4. Click Confirm and Complete.
  5. Click Add User.
  6. App Layering 2306 grant the Reader role by default. You can change the role by editing the user.
  7. Click the drop-down to see other available roles.
  8. When done, click Confirm and Complete.

In the older Internet Explorer interface:

  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.

User Layers Storage Locations

ELM 4.14 and newer support User Layers.

File shares for User Layers are configured at System > User Layer Storage 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. The first one you add is the default Storage Location for users not assigned to any other Storage Location.
  4. Then you can add more Storage Locations for specific user groups.

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

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 2403 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. 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.
  12. 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

127 thoughts on “App Layering – Enterprise Layer Manager (ELM) 2403”

  1. Awesome article! Thank you!
    We have multiple app layers, and I need to uninstall one app, but I don’t know which layer it’s in. I’m wondering if there is any practical way of determining which app is installed in each layer, without, creating a new version of each, and looking in appwiz.cpl.

  2. It is indicated that “App Layering v2208” only support CVAD-v2203 in its release note, could this create any issues when used with CVAD-2203CU1/2, CVAD-v2206, CVAD-v2209?

    We would like to move to latest CR of CVDA components.

  3. Hi Carl,

    I am trying to export the layers from the ELM console, while doing so, am encountering an error which says “Access to the path ‘/mnt/maserviceshare/………/System Volume Information’ is denied”. I am assuming this is the message from the appliance itself, i have tried to use a domain account which has administrator access and with the built in Administrator also, getting the same error message.

      1. Yes I see that link and have followed it to the page, but the page says:
        This script has been written to support PVS Powershell CMDLETS for PVS 7.7 and later. A separate script is required for earlier versions of PVS.
        There is no links for the earlier versions of PVS?

  4. We currently have the ELM deployed as a VM on Hyper-V. We need to move to VMware vSphere, and wondering if there is an export/import option to export config from ELM1[on Hyperv] and import in ELM2[On VMware]

  5. 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?

  6. 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!!

  7. 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?

  8. 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

  9. 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.

  10. 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?

  11. 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.

  12. 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

Your email address will not be published. Required fields are marked *