Author: Carl Stalhood

Navigation

This page assumes the Enterprise Layer Manager (ELM) has already been imported and configured. This page is based on VMware vSphere. For Hyper-V and PvS focused instructions, see Create and update the OS Layer by CTP George Spiers. For Azure, see How to configure Citrix Cloud – App Layering 4.x to deliver virtualized apps and Office 365 caching – User Layers for XenApp and XenDesktop Service Cloud Workspaces in Microsoft Azure by CTP Christiaan Brinkhoff.

• Change Log
• Layers Overview
• Operating System Preparation
• vSphere Connector
• Platform Layer
• Update OS and Platform Layers (Add Versions)
• App Layers, Image Templates, and Publishing (separate page)

Change Log

• 2024 March 27 – Updated OS Prep section for Layering 2403.
• 2022 July 18 – added link to Citrix Blog Post Citrix App Layering and reporting.
• 2021 Dec 25 – Platform Layer – added screenshots of new HTML5 interface.
• 2021 Feb 22 – Layers Overview – added link to Citrix Blog Post How to approach designing your app layering strategy
• 2020 July 14 – OS Layer – added link to CTX255870 Windows 10 v2004 – Citrix Known Issues

Layers Overview

25-page Citrix App Layering Reference Architecture at Citrix Tech Zone details the following:

• Why App Layering
• Technical Overview of Citrix App Layering
• Types of Layers
• App Layering Integration with Citrix Provisioning and Citrix Machine Creation Services
• Cross-Platform Support
• App Layering Communication Flow
• Availability, Backup, and Recovery – including User Layers

Enterprise Layer Manager (ELM) uses several types of layers:

• Operating System Layer
• Platform Layer
• Application Layer
• Image Template
• User Layer

The master versions of all Layers are stored inside the Enterprise Layer Manager virtual appliance.

Citrix Blog Post How to approach designing your app layering strategy describes in which layer to install an application.

Citrix CTX225952 4.x Layering Best Practices

Layer Report – lists all of the Layers and the information associated with the layers. See Rob Zylowski at Citrix Blog Post Citrix App Layering and reporting.

Operating System Layer

Operating System Layer is just the base OS (with patches) and VMware Tools. Other components are usually installed in Platform and Application Layers.

• If you install .NET Frameworks in the OS Layer, then you only need to run Windows Updates on the OS Layer. However, Office should always be installed in an Application Layer.
• Windows Store apps should be removed from the OS Layer, not other layers.

Platform and Application Layers are tied to the OS Layer – The remaining layers (Platform and Application) are created from an OS Layer. These layers are linked to one OS Layer, and can’t be used on any other OS Layer.

• If you upgrade the hypervisor tools in the OS Layer, then you might have to recreate the Platform Layer.

Only OS Layer captures changes to local groups and local apps – Any application that creates local users (e.g. XenApp 6.5) should be installed in the OS Layer. Platform Layer and Application Layers do not capture changes to local groups or local users.

Platform Layer

Platform Layer is the highest priority layer and should contain the following: (from CTX225997 Considerations When Creating a Platform Layer in Citrix App Layering 4.x)

• Citrix Virtual Delivery Agent, or VMware Horizon Agent.
• Citrix Provisioning Services Target Devices Software
• NVIDIA Drivers
• Join the Domain
• Citrix Receiver – for the Single Sign-on Component
• Citrix Workspace Environment Management Agent
• Imprivata
• Hypervisor Tools – if packaging or publishing to a different hypervisor than originally used to create the OS Layer.

SAM database changes (local users, local groups) are not captured in the Platform Layer. You might have to use group policy to create and populate local groups. For example, Citrix Virtual Delivery Agent creates local users adds domain users to local groups. See Direct Access Users Group Missing All Layers at Citrix Discussions.

• Domain Join in Platform Layer does not capture adding Domain Admins to local Administrators group and Domain Users in the local Users group. Use Group Policy Restricted Groups or Group Policy Preferences Local Users and Groups to add these Domain Groups to the Local Groups.
  
  
• Here are some additional settings in a Group Policy at Computer Configuration > Preferences folder > Control Panel Settings  Right-click the Local Users and Groups node, point to New, and select Local Group. More info at CTX259057 VDAs are not registering using a published image – Use GPO/GPP to add the proper accounts and services.
  • Action – Update – Group – Remote Desktop Users – Add Members “DOMAIN\Domain Users”
  • Action – Update – Group – Remote Desktop Users – Add Members “NT AUTHORITY\Authenticated Users”
  • Action – Update – Group – Performance Log Users – Add Members “NT Service\CitrixTelemetryService”
  • Action – Update – Group – Performance Monitor Users – Add Members “NT Service\BrokerAgent”
  • Action – Update – Group – Administrators – Add Members DOMAIN\Your_Citrix_Admins_Group
  • Action – Create – Group – Anonymous
  • Action – Create – Group – Direct Access Users – Add Members DOMAIN\Your_User_Group

Windows 10/11 apps should be removed from the OS Layer, not from the Platform Layer.

An Image Template (the composed machine that is published to the hypervisor) can contain only one Platform Layer. If you are creating a Platform Layer for Citrix Provisioning Services, then that one Platform Layer should include both the Citrix VDA and the Citrix PvS Target Device Software.

Application Layers

Application Layers contain anything not in the OS Layer or Platform Layer, including the following:

• Applications
• Antivirus
• Print Drivers
• SCCM Client

Per-user settings (profile changes) are not captured in an Application Layer.

When creating a Layered Machine, there are two methods of merging the Application Layers:

• Pre-boot – ELM merges the App Layers with the OS Layer and Platform Layer to create a single monolithic disk file. This method provides the greatest application compatibility. Use this method for Apps with boot time services or drivers.
• Elastic – When the user logs into a Layered Machine, a service looks in a file share for any Elastic Layers assigned to the user, and merges (mounts) them as the user logs in. Different users can have different Elastic Layers, even on multi-user Remote Desktop Session Host (XenApp) machines. However, Elastic Layering doesn’t work for apps that need boot-time services/drivers.

A single App Layer can be merged using either of these methods. If the App Layer doesn’t work Elastically, then you can mount it Pre-boot (Image Template) instead. There is no need to create separate App Layers for each mounting method.

Elastic App Layers are stored in a SMB file share. You can use any desired method to provide High Availability for this file share, including: Scale Out File Server, DFS Namespace/Replication, etc.

FSLogix creates local groups every time the service restarts, thus it works when installed inside an Application Layer.

Image Template

Image Template contains one OS Layer, one Platform Layer, and zero or more App Layers. The App Layers assigned in the Image Template are merged pre-boot.

You then Publish the Image Template to your hosting platform.

• For MCS, the Template is pushed to a hypervisor (e.g. vSphere) virtual machine, which becomes the master image for an MCS Catalog.
• For PvS, ELM creates a VHD file, and pushes it to a PvS vDisk Store, so you can assign it to Target Devices.

For Elastic Layers, you must enable Elastic Layers in the Image Template.

User Layers

User Layers allow users to install their own applications. In ELM 4.14 and newer, User Layers are fully supported.

User Layers require additional consideration for backup, replication, and recovery.

User Layers are tied to OS Layer – From Gunther Anderson: “Like App and Platform Layers, User Layer disks are tied to the OS layer they were originally built from. If you have a user login to images from two different OS layers, you will see the User Layer disks in two different directories on the share, one for each OS layer. The image itself knows what OS layer it was built from, and the ULayer service uses that information.”

• If you want profile portability, store the profile outside of the User Layer by implementing Citrix Profile Management.

The default size for User Layers is 10 GB. You can change this size by setting HKLM\Software\Unidesk\Ulayer\DefaultUserLayerSizeInGb on the managed machines. Source = Understanding Elastic Layering > Scaling (tab) > User Layer Size.

Layering Tips

From Citrix Blog Post 5 Tips for Packaging Your Apps with Citrix App Layering:

1. .NET Frameworks go in the OS Layer
   1. Store apps are removed from the OS Layer.
2. Keep the layer as clean and as small as possible
   1. A packaging machine will not be part of your domain
   2. Delete any installers from the desktop, delete any temp directories, and empty the recycling bin
   3. If Windows Updates, delete the contents of C:\Windows\SoftwareDistribution\Download
3. Underlying applications should be layered first, and then selected as prerequisite layers when you go to create a layer for the subsequent application
4. Use  Application Layer Recipes
   1. Turn off the application’s auto-updater
   2. For antivirus, follow the manufacturer’s steps to “generalize” or remove any unique client identifiers
   3. Handle application licensing – rearm, activation, etc.
5. Run ngen.exe update

Also see Citrix CTX225952 4.x Layering Best Practices:

• Operating System Layer:
  • Application Layers are tied to the Operating System Layer.
  • ELM automatically upgrades OS Layer drivers. However, OS Layer Scripts should be updated reinstalling the Machine Tools.
  • .NET should be in the OS Layer.
  • OS Layer is lowest priority.
  • Patch OS by creating an OS Layer Version.
  • When patching, ensure Windows is activated.
  • VMware Tools goes in the OS Layer. Update it too.
  • Windows Store apps should be removed from the OS Layer.
• Application Layers:
  • Per-user profile settings are not captured.
  • Local users and local groups are not captured. Use Group Policy Restricted Groups instead.
  • A single utility layer can include Java, Flash, Adobe Reader.
  • Turn off application automatic updates.
  • If domain membership required for an app installation, join domain, install app, remove from domain.
  • Antivirus can go in OS Layer or App Layer.
  • Printer drivers can be layered – but not elastically
  • Use Layer Recipes.
  • All Office apps needed by a machine/user should be combined into a single Office Layer
  • Office cannot be elastically layered
  • When patching Office, update the OS Layer first.
  • Max 50 layers per desktop.

CTX226984 App Layering/Unidesk: The list of Windows Updates is usually wrong in app/platform layers and published images/desktops.

Operating System Preparation

1. See Citrix CTX225952 4.x Layering Best Practices
2. Windows Server 2019 – Windows Server 2019 is supported in App Layering 1905 and newer
3. Office 2019 – Office 2019 is supported in App Layering 1905 and newer
4. Windows 11 is supported in App Layering version 2112 and later
5. Windows 10
   1. Windows 11 22H2 and Windows 10 22H2 are supported in App Layering 2211 and newer.
   2. Windows 11 is supported in App Layering 2112 and newer.
   3. Windows 10 version 21H2 is supported in App Layering 2110 and newer.
   4. Windows 10 version 21H1 is supported in App Layering 2107 and newer.
   5. Windows 10 version 20H2 is supported in App Layering 2011 and newer.
   6. Windows 10 version 2004 is supported in App Layering 2008 and newer.
   7. Windows 10 version 1909 is supported in App Layering 2001 and newer.
6. Create a virtual machine.
7. If vSphere:
   1. Make sure your OS Layer creation machine has a NIC of type VMXNET 3.
      
   2. Paravirtual SCSI controllers are supported in App Layering 2001 and newer.
      
   3. On the VM Options tab, expand Boot Options, and make sure the Firmware is BIOS, not EFI.
      
8. EFI:
   1. App Layering 2003 and newer has a ImportOsLayer.ps1 script that can import an EFI machine.
   2. Connectors with Compositing Engine enabled support EFI.
   3. Older versions of App Layering cannot import an EFI OS Layer.
   4. vSphere 6.7 defaults to EFI for new VMs.
9. Install an operating system (Windows 11, Windows 10, or Windows 2022/2019/2016), and patch it.
   • If you in-place upgrade Windows 10 to a newer version, you might have to use diskpart to delete the Recovery Partition. See CTX226407 App Layering: Windows 10 upgrade may result in new Recovery Volume partition.
   • CTX255870 Windows 10 v2004 – Citrix Known Issues has a couple issues related to Citrix App Layering.
10. Install VMware Tools.
    
11. DHCP – Make sure the NIC is set to DHCP.
    
12. Workgroup – Don’t join the template machine to the domain. Leave it in a workgroup.
    
13. RDSH – For RDSH machines, Citrix recommends installing RDSH in the OS Layer instead of the Platform Layer.
    
14. Remote Desktop – Enable remote connections (Remote Desktop).
    
    
15. Install Windows Updates.
    
16. Disable Automatic Updates on the template machine. You can use layers to install updates. An easy method to disable it is in Group Policy (gpedit.msc) at Computer Configuration | Policies | Administrative Templates | Windows Components | Windows Update | Manage End User Experience | Configure Automatic Updates. Disable the setting.
    
17. To stop Windows from performing maintenance and consuming 100% CPU, set the following registry value: (source = Win 10 Image – CPU Utilization 100% non-stop at Citrix Discussions):
    • HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Schedule\Maintenance
      • MaintenanceDisabled (REG_DWORD) = 1
18. If Citrix Provisioning, George Spiers says IPv6 should be disabled.
19. Go to the downloaded App Layering 2403 files, right-click the citrix_app_layering_os_machine_tools_24.3.0.exe file, and click Run as administrator.
    
20. Click Yes to extract the files.
    
21. If you look on the taskbar, you might see an open program called Set KMS Version.
    
22. Click Use KMS.
    
23. Click Close when prompted a reboot is needed.
    
24. Then close the window.
    
25. If Set KMS Version did not run automatically, then manually run C:\Windows\Setup\scripts\SetKMSVersion.hta as administrator (elevated).
    1. Shift right-click the file to copy its full path.
       
    2. Open command prompt as administrator, paste the path, and run it from there.
       
    3. Click Use KMS.
       
    4. This adds the file runipkato.cmd to C:\Windows\Setup\scripts\kmsdir, which ELM will run when it publishes the image. The script installs the KMS Client key and activates it.
       
26. If you have run KMS Setup multiple times (usually due to Machine Tools upgrades), check the registry for duplicates and remove the duplicates.
    1. In regedit, go to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Group Policy\Scripts\Startup\0\0. You should see kmssetup.cmd.
       
    2. If there are other registry keys named 1 or higher, check them for kmssetup.cmd. If true, then delete the duplicate keys so that only 0 remains.
       
    3. See CTX238316 After upgrading the OS Machine Tools, kmssetup.cmd runs twice at startup for more details.
27. If this is a Windows 10 or Windows 11 virtual machine, and if you want to remove Store apps, remove them from the OS Layer instead of the Platform Layer.
    1. In App Layering 4.11 and newer, Store apps are supported, and it is no longer necessary to remove them.
    2. App Layering 4.7 and newer has a script at C:\Windows\Setup\Scripts\RemoveStoreApps.cmd that can remove the store apps. Note: this script removes Calculator, so you’ll probably want to find a replacement Calculator.
       
    3. Citrix Optimizer can remove Store apps.
       
    4. The Citrix Optimizer community marketplace at https://raw.githubusercontent.com/ryancbutler/Citrix_Optimizer_Community_Template_Marketplace/master/communitymarketplace.xml also has an App Layering Supplement.
       
       
28. Run setup_x64.exe from C:\Windows\Setup\scripts. Make sure you run it elevated.
    
29. In the Welcome to the InstallShield Wizard for the Citrix App Layering Image Preparation Utility 23.12.0.4 page, click Next.
    
30. In the Specify your answer file page, click Next.
    
31. In the InstallShield Wizard Completed page, click Finish.
    
32. CTP George Spiers Citrix App Layering Preparation Script: runs a number of tasks to clean out temporary folders, clear out Event Log entries, remove ghost devices from Device Manager, etc.
33. Run the ImportOsLayer.ps1 script to import your new OS Layer to ELM. Newer versions of ELM only support the ImportOsLayer.ps1 method of creating an OS Layer.
    
    

vSphere Connector

ELM uses Connectors to communicate to push images and layers to various hypervisors.

1. In App Layering 2202 and newer, you can use the new HTML5 interface to create Connectors.
   
   1. In ELM 4.11 and newer, in the Internet Explorer Silverlight console, you can create or edit connectors at System > Connectors. This page also shows Connector Cache information. Caching improves performance of the connectors.
      
2. See System requirements at Citrix Docs for the list of supported hypervisors and brokers.
3. To create the vSphere connector, in the Choose a Connector Type window, select VMware vSphere.
   • For configuration instructions for the other connectors, see Connector configurations at Citrix Docs.
4. Click New.
   
   
5. In App Layering older than version 2304, a new tab opens. Version 2304 and newer have a new interface for configuring the Connector.
   
6. Give the Connector a name (e.g., vCenter name). The Connector specification includes specific storage, so the Connector name should indicate the storage name.
   
   
7. Enter the vCenter FQDN and service account credentials.
   • The vCenter permissions needed by the service account are detailed at vSphere Permissions at Citrix Docs.
8. Click Check Credentials.
   
   
9. Scroll down and use the drop downs to select where you want Packaging VMs and Published Templates to be created.
   • The Packaging VMs and Published Templates will be created under the Virtual Machine Folder that you specify here.
     
10. If MCS, in the Virtual Machine Template (optional) field, search for a Template VM that will be copied to create the MCS master image. The Template VM needs CPU, Memory, and GPU settings, but no disks. See Required information for this Connector Configuration at Citrix Machine Creation Services for vSphere Connector Configuration at Citrix Docs.
    • To ensure that the published images have the correct time zone, it may help to generate a new template for your Connector by having (or building) a Windows VM that has booted in the correct time zone. Shut it down, clone it, delete the attached disk from the clone, and convert that to a template for your Connector configuration in the Layering Management Console. More info at CTX230562 App Layering: Machine time on a published image is wrong at first boot.
11. Packaging Cache Size in GB speeds up App Layer creation operations if you are creating multiple App Layers for the same OS/Platform combination. The size should be greater the size of the OS/Platform combinations.
    
12. Offload Compositing – at the bottom of the connector, make sure Offload Compositing is enabled to speed up provisioning operations. In 2304 and newer, click Confirm and Complete.
    
13. In older versions click Test.
    
    1. When the Test is successful, click Save.
       
    2. Then click Close.
       

Platform Layer

Create Packaging VM

1. See Citrix CTX225952 4.x Layering Best Practices.
2. See Citrix CTX225997 Considerations When Creating a Platform Layer in Citrix App Layering 4.x.
3. Create your Hypervisor Connector before you create the Platform Layer. In the new HTML5 console in App Layering 2202 or newer, click Connectors on the left. Or in the Internet Explorer Silverlight console, go to System > Connectors to create a Connector.
   
   
4. In the HTML5 console, click Layers on the left, switch to the Platform Layers tab on the right, and then click Create Platform Layer.
   
   1. In the older Internet Explorer Silverlight console, in the Layers tab, Platform Layers sub-tab, right-click in the grey area, and click Create Platform Layer.
      
5. In the Layer Details page, give the Platform Layer a name and version. Note: Platform Layers are linked to OS Layers, so it’s best to indicate which OS Layer this Platform Layer is based on. You can’t use a Platform Layer created on one OS Layer on a different OS Layer.
6. Enter a version number.
7. Specify a Max Layer Size. Note: the packaging machine is thick provisioned using the size specified here, plus the size of the OS Layer.
8. In the HTML5 interface, scroll down.
   
   1. In the Silverlight interface, click Next (down button).
      
9. In the OS Layer page, select the OS Layer (and layer version) this Platform Layer will be based on.
10. In the HTML5 interface, scroll down.
    
    1. In the Silverlight interface, click the next button (down arrow).
       
11. In the HTML5 interface, change the selection to This platform layer will be used for publishing Layered Images.
    1. Use the drop downs to select the Hypervisor, Provisioning Service, and Connection Broker. These can be changed later.
    2. Select an existing vSphere connector.
    3. For Packaging Disk Filename, enter a name for the .vmdk disk that will be created in vSphere. Click Confirm and Complete.
       
    4. Then click Create Layer.
       
12. In the Internet Explorer Silverlight interface, in the Connector page, if you already have a vSphere connector, select it, and click Next. If you don’t already have a vSphere connector, then click New to create one. Click the down arrow.
    
    1. In the Platform Types page, change the selection to This platform layer will be used for publishing Layered Images. The other selection is if you want to deploy the vSphere OS Layer on a different hypervisor (e.g. Azure).
    2. Use the drop downs to select the Hypervisor, Provisioning Method, and Connection Broker. These can be changed later. Click the down arrow.
       
    3. In the Packaging Disk page, enter a name for the .vmdk disk that will be created in vSphere. Click the down arrow.
       
    4. In the Icon Assignment page, select an icon, or upload a new one. Click the down arrow.
       
    5. In the Confirm and Complete page, click Create Layer.
       
13. In the HTML5 interface, on the left is the Tasks node showing you the current progress. Click View Details.
    
    
    1. In the Silverlight interface, on the bottom of the screen, open the Tasks pane.
    2. Click the information icon to view what the task is doing.
       
14. Eventually it will say Pending (Action Required), meaning it’s waiting for you to perform the packaging in vSphere.
    
    

Edit Packaging VM

1. In vSphere Web Client, in the VMs and Templates view, expand the Layering folder, expand Packaging VMs, and click the new Packaging Machine.
   
2. If you edit the VM’s hardware, and if Offload Compositing is enabled, then the Hard Disk is Thin Provisioned.
   
   1. If Offload Compositing is not enabled, then notice that the disk is Thick Provisioned.
      
3. Open the VM’s console and login to the machine.
4. Join it to the domain. Only join the Platform Layer to the domain. OS Layer and App Layers must not be joined to the domain. You’re welcome to change the computer name.
   
   • After joining the domain, move the computer object to your VDA OU so the GPO computer settings are applied to the Platform Layer.
     
5. You can now install VDA software.
   • VDA 2112 is supported with App Layering 2112 and newer.
   • VDA 1912 LTSR is supported with App Layering 2001 and newer.
   • VDA 1909 is supported with App Layering 1910 and newer.
   • VDA 1906 is supported with App Layering 1907 and newer.
   • VDA 1903 is supported with App Layering 1905 and newer.
     
     
6. Feel free to reboot the Packaging VM.
   
7. Rob Zylowski at Imprivata App Layers at Citrix Discussions recommends installing Imprivata in the same Platform Layer that contains the VDA.
8. According to Direct Access Users Group Missing All Layers at Citrix Discussions, the Platform Layer does not capture or merge changes to local groups.
   1. Use Group Policy Restricted Groups or Group Policy Preferences Local Users and Groups to configure local groups.
      
   2. At Computer Configuration >Preferences folder >Control Panel Settings, right-click the Local Users and Groups node, point to New, and select Local Group. More info at CTX259057 VDAs are not registering using a published image – Use GPO/GPP to add the proper accounts and services.
      • Action – Update – Group – Users – Add Members: “DOMAIN\Domain Users”
      • Action – Update – Group – Administrators – Add Members: “DOMAIN\Your_Citrix_Admins_Group”, “DOMAIN\Domain Admins”
      • Action – Update – Group – Remote Desktop Users – Add Members: “NT AUTHORITY\Authenticated Users”
      • Action – Update – Group – Performance Log Users – Add Members: “NT Service\CitrixTelemetryService”
      • Action – Update – Group – Performance Monitor Users – Add Members: “NT Service\BrokerAgent”
      • Action – Create – Group – Anonymous
      • Action – Create – Group – Direct Access Users – Add Members: “DOMAIN\Your_RDP_Allowed_User_Group”
9. If Citrix Provisioning:
   1. Install the Citrix Provisioning Target Device Software in the Platform Layer. The ELM Templates only allow one Platform Layer per template, so you’d need to install both VDA and Provisioning Services Target Device components in a single Platform Layer.
      
   2. Rearm KMS licensing (slmgr /rearm). MCS does this automatically during Image Prep.
      
10. From Citrix CTX225997 Considerations When Creating a Platform Layer in Citrix App Layering 4.x): Additional software to install in the Platform Layer:
    • NVIDIA Drivers
    • Join the Domain – after joining, login as network account, then login as local account, and delete the profile of the network account.
    • Citrix Workspace App – for the Single Sign-on Component
    • Citrix Workspace Environment Management Agent
    • Hypervisor Tools – if packaging or publishing to a different hypervisor than the one originally used to create the OS Layer.
11. Windows 10/11 apps should be removed from the OS Layer, not from the Platform Layer.
12. CTX226984 App Layering/Unidesk: The list of Windows Updates is usually wrong in app/platform layers and published images/desktops.
13. When done installing components, finalize the layer:
    1. CTP George Spiers Citrix App Layering Preparation Script: runs a number of tasks to clean out temporary folders, clear out Event Log entries, remove ghost devices from Device Manager, etc.
    2. Double-click the Shutdown for Finalize icon on the desktop. If it finds issues, it will tell you what to do (e.g. reboot needed).
       
    3. If it tells you that you need to run ngen, then run the following commands:
       

       "c:\windows\Microsoft.NET\Framework64\v4.0.30319\ngen.exe" update
       "c:\windows\Microsoft.NET\Framework\v4.0.30319\ngen.exe" update

    4. Otherwise, it will shut down the VM.
14. If Offload Compositing is enabled in your Connector, then the Packaging VM will reboot into Windows PE and automatically run the CompositingEngine.
    
15. ELM will automatically transfer the files from the Compositing Engine. You don’t have to click Finalize.
    
    
16. If Compositing Engine is not enabled in your Connector:
    1. Back in the ELM Internet Explorer Silverlight Console, in Layers > Platform Layers, right-click the Editing layer, and click Finalize.
       
    2. In the Confirm and Complete page, click Finalize.
       
    3. You can click the information icon next to the running task to see what it’s doing.
       
       
17. Eventually the icon will say Deployable.
    
    
18. In the HTML5 interface, the tabs show you details on the layer.
    
    1. In the Internet Explorer Silverlight interface, you can click the information icon on the Platform Layer to view its details.
       
       

Next Steps

• Create App Layers, Image Templates, and Publish Them

Update OS or Platform Layers

1. In the HTML5 Interface, select a layer, switch to the Version Information tab, and click Add Version.
   
   1. In the Silverlight interface, right-click an OS Layer or a Platform Layer, and click Add Version.
      
2. In the Version Details page, select a Base Version that you want to update. In the New Version field, enter a new version. In HTML5 Interface, scroll down. In Silverlight interface, click Next.
   
   
3. In the OS Layer page, select an OS Layer version, and scroll down or click Next.
   
   
4. In the HTML5 Interface, in the Platform Types section, most of this should already be filled in. Choose your Connector Configuration and then click Confirm and Complete.
   
5. In the Internet Explorer Silverlight interface, in the Connector page, select a Connector, and click Next.
   
   1. In the Platform Types page, click Next.
   2. In the Packaging Disk page, click Next.
   3. In the Confirm and Complete page, click Add Version.
      
6. The Tasks page and Task Details shows the current progress and will eventually say Action Required.
   
   
   
7. When the Packaging Machine is deployed, you can connect to its console and perform any desired updates.
   
   • If you in-place upgrade Windows 10 to a newer version, you might have to use diskpart to delete the Recovery Partition. See CTX226407 App Layering: Windows 10 upgrade may result in new Recovery Volume partition.
8. When done installing updates, finalize the layer:
   1. George Spiers Citrix App Layering Preparation Script: runs a number of tasks to clean out temporary folders, clear out Event Log entries, remove ghost devices from Device Manager, etc.
   2. Double-click the Shutdown for Finalize icon on the desktop. If it finds issues, it will tell you what to do (e.g. reboot needed). Otherwise, it will shut down the VM.
      
9. If Offload Compositing engine is not enabled in your Connector:
   1. When done updating the Packaging Machine, right-click the Layer that is marked as Editing, and click Finalize.
      
   2. In the Confirm and Complete page, click Finalize.
      
10. View the task details to see the current progress.
    
    
11. To confirm that you have a new version, the layer’s Version Information tab shows the new version. Or in the Silverlight interface move your mouse over the layer icon, and click the information icon. The available versions are shown.
    
    
    
12. There are two methods of assigning a new version: one image at a time, or multiple images.
13. To edit one image:
    1. Go to the Images tab.
    2. Select an Image, and click Edit Template.
       
    3. Scroll down or click the OS Layer or Platform Layer page.
    4. Click the plus arrow next to a Layer and select the new version. Then complete the wizard.
       
       
14. To update multiple images:
    1. In HTML5, select the Layer, switch to the Version Information tab, select a version, and click Update Assignments.
       
       1. In Silverlight, on the Layers tab, right-click the updated layer, and click Update Assignments.
          
       2. In the Select Version page, select the version you want to assign, and click Next.
          
    2. In the Image Template Assignment page, select the templates you want to update, and scroll down or click Next.
       
       
    3. Click Confirm and Complete, or in the Confirm and Complete page, click Update Assignments.
       
       
15. Once an image has a new version assigned, go to the Images tab, and republish the image.
    
    

Navigation

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

• Change Log
• Licensing
• Upgrade Enterprise Layer Manager
• Import Enterprise Layer Manager Appliance
• ELM IP Address
• First Login
• Appliance Certificate
• File Share
• Active Directory
• User Layers Storage Locations
• Provisioning Services Publishing Agent
• OS Layer and Platform Layer (separate page)
• App Layers, Image Templates, and Publishing (separate page)

Change Log

• 2024 November 7 – Updated Upgrade section, Import Appliance section, and PVS Agent section for Layering 2409
• 2023 July 2 – Updated Upgrade section, Import Appliance section, and PVS Agent section for Layering 2306
  • RBAC available in 2306+
• 2022 May 14 – Updated Upgrade section, Import Appliance section, and PVS Agent section for Layering 2204
  • Added some newer screenshots/procedures for the HTML5 interface in Layering 2204.
• 2022 Mar 10 – Updated Upgrade section, Import Appliance section, and PVS Agent section for Layering 2202
  • In version 2202 and newer, upgrades can now be performed in the HTML5 interface.

Licensing

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.

If you are upgrading from 2403 or older, first upgrade the existing appliance to version 2403.9. Then deploy a new 2409 appliance. Then run the migration wizard from the 2403.9 appliance.

To upgrade the older appliance:

1. When you login to the ELM, 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 version 2403.9 upgrade package from Citrix App Layering 2403 at Citrix Downloads. Look for the section named For an existing deployment, download the upgrade package.
      
   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.9.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.
      
      
3. Click Confirm and Complete.
   
4. In the Confirm Upgrade page, click Upgrade.
   
   
5. Wait for the upgrade to complete.
   
6. Then click Return to login and login.
   
7. Click Dismiss acknowledging that connector caches have some items removed.
   
8. On the top right, click your username and then click About to see the current version, which should be 24.3.9.
   
   
9. Import a new ELM with version 2409 or newer.
   
10. In the older 2403.9 appliance, click your name on the top right and then click Migrate Appliance.
    
11. Enter the address for the new 2409 or newer appliance.
12. Change Migration Reason to Move.
13. Click Confirm and Complete.
    
14. Click Confirm. Click Migrate.
    
    
15. In the Tasks page, click View Details for the Active task to see the progress.
    

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

Reference Architecture: App Layering:

• 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 2409 Appliance Installation Package from Citrix Downloads.
   
2. After downloading, extract the 2409.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_24.9.0.1.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 Customize template page, click Next.
    
11. In the Ready to complete page, click Finish.
    
12. See Firewall ports at Citrix Docs.
    • ELM requires TCP 443 access to every ESXi host. (Source = Citrix CTX228486 Unable to import App Layering OS Layer to ELM from vSphere)

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, press enter to show the login prompt, and then login to the console as administrator with a password of Unidesk1.
   
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.
    

First Login

1. In App Layering 2206 and newer, use Edge or Chrome 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.
   
   You then see the Get Started wizard.
   

Appliance Certificate

1. In the HTML5 console, go to System > HTTP Certificate Settings.
   
2. In HTML5 console, on the right, click Upload to replace the default management certificate.
   
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.
   
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.
   

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.
      

Active Directory

In App Layering newer than 2204, you 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.
   

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 2409 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

• Create OS Layer and Platform Layer