App Layering – OS Layer and Platform Layer

Last Modified: May 19, 2017 @ 7:30 pm


This topic assumes the Enterprise Layer Manager has already been imported and configured. See Create and update the OS Layer in Unidesk 4.0.8 by George Spiers for Hyper-V and PvS focused instructions.

Layers Overview

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.


Operating System Layer is just the base OS (with patches) and VMware Tools. There’s usually no need to install anything else.

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.

Any application that creates local users (e.g. XenApp 6.5) should be installed in the OS Layer.


Platform Layer contains the following:

  • Citrix Virtual Delivery Agent, or VMware Horizon Agent.
  • Citrix Provisioning Services Target Devices Software
  • Hypervisor Tools – if packaging or publishing to a different hypervisor than originally used to create the OS 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 contain anything not in the OS Layer or Platform Layer, including the following:

  • Applications
  • Antivirus
  • Print Drivers
  • Citrix WEM Agent
  • SCCM Client

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.


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.


User Layers allow users to install their own applications. In ELM 4.2, User Layers are a lab feature.

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

Operating System Preparation

  1. Create a virtual  machine.
  2. If vSphere, make sure your OS Layer creation machine has VMXNET3 NIC.
  3. GPT and UEFI are not supported, only MBR and BIOS. See Unidesk 4.1 – New VMware Connector – page not found at Unidesk forums.
  4. Install an operating system, and patch it.
  5. Install VMware Tools.
  6. Don’t join the template machine to the domain. Leave it in a workgroup.
  7. 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) > Computer Configuration | Policies | Administrative Templates | Windows Components | Windows Update | Configure Automatic Updates. Disable the setting.
  8. If PvS, George Spiers says IPv6 should be disabled.
  9. Go to C:\Windows\Setup, and create the Scripts folder.
  10. Go to the downloaded App Layering files, right-click the citrix_app_layering_os_machine_tools_4.2.0.exe file, and click Run as Administrator.
  11. Click Install.
  12. From MCS Error – ImagePreperationOSRearmFailed at Unidesk forums. Citrix recommends running  C:\Windows\Setup\scripts\SetKMSVersion.exe as administrator (elevated).  💡
  13. Click Save Script.
  14. 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.
  15. You can optionally configure an unattend file to join the Layered machines to the domain. If MCS, you can skip this step, and MCS will do it for you. For PvS, you can manually join the domain when creating a Platform Layer. Or you can use PowerShell for Advanced Domain Join Operations. The unattend file is more appropriate for full clone VMs. The unattend tool also sets up KMS as described earlier.
    1. To create an unattend file, in C:\Windows\Setup\Scripts, right-click Unattend.exe, and run as administrator.
    2. At the top of the page, select the correct operating system.
    3. Make selections for the other fields.
    4. When choosing to join the domain, note that Domain join credentials are stored in the unattend.xml file in plain text.
    5. Continue to scroll down and enter configuration settings.
    6. At the bottom of the window, click Save File
    7. The tool creates the SetupComplete.cmd file.
  16. In C:\Windows\Setup\Scripts, run Optimize64.exe as administrator.
  17. At the top, select your operating system.
  18. Scroll down. As you scroll, review the changes it’s going to make. Then click Save File.
  19. Click OK when Optimizations have been saved. Then close the optimization tool.
  20. Rob Zylowski at Publishing a layered image fails every time with the same error at Citrix Discussions says that OfficeHub in Windows 10 1607 might interfere with Layering. Run the following to remove it.  💡
    get-appxpackage -name "*officehub*" | remove-appxpackage
    Get-AppxProvisionedPackage -Online | where Displayname -EQ "Microsoft.MicrosoftOfficeHub" | Remove-AppxProvisionedPackage -Online
  21. Run setup_x64.exe from C:\Windows\Setup\scripts. Make sure you run it elevated.
  22. In the Welcome to the InstallShield Wizard for the Citrix App Layering Image Preparation Utility page, click Next.
  23. In the Specify your answer file page, click Next.
  24. In the InstallShield Wizard Completed page, click Finish.
  25. Shut down the machine.

Import OS Layer

  1. In the ELM Management Console, go to the Layers tab.
  2. Right-click in the grey area, and click Create OS Layer.
  3. In the Layer Details page, give the OS Layer a name and version.
  4. Specify a Max Layer Size. Note: the packaging machine is thick provisioned using the size specified here.
  5. Click the down arrow to proceed to the next page.
  6. In the Connector page, if you already have a vSphere connector, select it, and click the down arrow. If you don’t already have a vSphere connector, then click New. ELM 4.1 and newer can import directly from vSphere.

    1. To create the vSphere connector, in the Choose a Connector Type window, select VMware vSphere, and click New.
    2. For info on the other connectors, see Connectors for publishing (vSphere environment) at
    3. A new tab opens.
    4. Give the Connector a name (e.g. vCenter name). The Connector specification includes specific storage, so the Connector name should indicate the storage name.
    5. Enter the vCenter FQDN and service account credentials. The vCenter permissions needed by the service account are detailed at vSphere Prerequisites at
    6. Click Check Credentials.
    7. Scroll down and use the drop downs to select where you want Packaging VMs and Published Templates to be created. Published Templates are later used by MCS to create more machines.
    8. The Packaging VMs and Published Templates will be created under the Virtual Machine Folder that you specify here.
    9. 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 Connector Configuration & Optional Script (Citrix MCS for vSphere) at
    10. Layer Disk Cache Size in GB might speed 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. See Layer Caching for faster App Layer creation at  💡
    11. Click Test.
    12. When the Test is successful, click Save.
    13. Then click Close.
  7. Back in the Connector page, select the vSphere connector, and click the down arrow.
  8. In the OS Disk Details page, click Select Virtual Machine.
  9. Click the … next to Virtual Machine.
  10. Select the OS Layer Virtual Machine, and click OK.
  11. Click OK.
  12. Click the down arrow.
  13. In the Icon Assignment page, select an icon, or upload a new one. Then click the down arrow.
  14. In the Confirm and Complete page,  you can enter a Comment to indicate who created this layer and when. Then click Create Layer.
  15. At the bottom of the screen, click the up chevron to display the Tasks pane.
  16. You’ll see a Running task. Click the information icon to view more details.

  17. Eventually it will say completed successfully.
  18. And the OS Layer will be Deployable.

Platform Layer

  1. In the Layers tab, right-click in the grey area, and click Create Platform Layer.
  2. 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.
  3. Specify a Max Layer Size. Note: the packaging machine is thick provisioned using the size specified here, plus the size of the OS Layer.
  4. Click Next (down button).
  5. In the OS Layer page, select the OS Layer this Platform Layer will be based on, and click the down arrow.
  6. 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.
  7. 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).
  8. Use the drop downs to select the Hypervisor, Provisioning Method, and Connection Broker. These can be changed later. Click the down arrow.
  9. In the Packaging Disk page, enter a name for the .vmdk disk that will be created in vSphere. Click the down arrow.
  10. In the Icon Assignment page, select an icon, or upload a new one. Click the down arrow.
  11. In the Confirm and Complete page, click Create Layer.
  12. On the bottom of the screen, open the Tasks pane.
  13. 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.
  15. In vSphere Web Client, in the VMs and Templates view, expand the Layering folder, expand Packaging VMs, and click the new Packaging Machine.
  16. If you edit the VM’s hardware, notice that the disk is Thick Provisioned.
  17. You can now access the console of the Packaging VM and install VDA software.
  18. Feel free to reboot the Packaging VM.
  19. According to Direct Access Users Group Missing All Layers at Citrix Discussions, the Platform Layer does not capture or merge changes to local groups. Therefore, the following VDA configurations would need to be performed using Group Policy.  💡
    1. Create Direct Access Users local group. Which allows non admin users to RDP the Server if needed. Add this group to RDP User Right.
    2. Add Domain Users or Authentication Users group to the local Remote Desktop Users (could also be to the local “Users” group)
    3. Add NT SERVICE\BrokerAgent account to the local Performance Monitor Users group
    4. Add NT SERVICE\CitrixTelemetryService account to the local Performance Log Users group
    5. Create Local Anonymous group
  20. If PvS:
    1. Join the machine to the domain. MCS does this automatically during Image Prep.
    2. Install the PvS Target Device Software. The Unidesk Templates only allow one Platform Layer per template, so you’d need to install both VDA and PvS Target Device components in a single Platform Layer.
    3. Rearm KMS licensing (slmgr /rearm). MCS does this automatically during Image Prep.
  21. When you are done installing VDA (and optionally PvS Target Device Software), 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.
  22. Back in the ELM Management Console, in Layers > Platform Layers, right-click the Editing layer, and click Finalize.
  23. In the Confirm and Complete page, click Finalize.
  24. You can click the information icon next to the running task to see what it’s doing.

  25. Eventually the icon will say Deployable.
  26. You can click the information icon on the Platform Layer to view its details.

Next Steps

Update OS or Platform Layers

  1. Right-click an OS Layer or a Platform Layer, and click Add Version.
  2. In the Version Details page, enter a new version, and click Next.
  3. In the OS Layer page, click Next.
  4. In the Connector page, select a Connector, and click Next.
  5. In the Platform Types page, click Next.
  6. In the Packaging Disk page, click Next.
  7. In the Confirm and Complete page, click Add Version.
  8. The task details shows the current progress.
  9. When the Packaging Machine is deployed, you can connect to its console and perform any desired updates. When you are done performing updates, double-click the Shutdown for Finalize icon on the desktop.
  10. When done updating the Packaging Machine, right-click the Layer that is marked as Editing, and click Finalize.
  11. In the Confirm and Complete page, click Finalize.
  12. View the task details to see the current progress.
  13. To confirm that you have a new version, right-click the Layer, and click Delete Versions.
  14. You can only delete versions that are not assigned to any Image.
  15. There are two methods of assigning a new version: one image at a time, or multiple images.
  16. To edit one image:
    1. Go to the Images tab. Right-click an Image, and click Edit Template.
    2. Click the OS Layer or Platform Layer page.
    3. Click the plus arrow next to a Layer and select the new version. Then complete the wizard.
  17. To update multiple images:
    1. 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.
    3. In the Image Template Assignment page, select the templates you want to update, and click Next.
    4. In the Confirm and Complete page, click Update Assignments.
  18. Once an image has a new version assigned, you must republish it.

59 thoughts on “App Layering – OS Layer and Platform Layer”

  1. I’m successfully using Citrix App Layering in a test environment, but have run into an interesting issue. I’m using Active Directory-Based Authentication for Windows 10 and Office 2016 Pro Plus (c2r). I’ve found that if I join the platform layer to the domain and install Office 2016 in the platform layer everything will work fine.

    If I attempt to create a separate layer for Office 2016, then I run into an issue where an Office app will need to repair itself. Once repaired, the application will close and work fine for the rest of my Citrix session.

    Do you know of any tricks for those of us using ADBA instead of KMS or MAK? It seems like Unidesk and Citrix are lacking documentation for this scenario.

  2. I’ve followed all of this creating an OS layer for Windows 2012R2 and then creating a Platform layer for VDA. The machine gets created under layering as VDAXXXXXXXXXX in VCenter and I can connect to the VM and see the 10GB UDiskBoot but there is no unidesk icon on the desktop to seal.

    If I install something then shutdown the machine and try to finalise the layer it complains saying it has a pending reboot task, presume this is due to the fact I haven’t run the sealing script/tool shutdown for finalise.

    So not sure what i’m doing wrong or why the icon on the desktop is not appearing, I’ve tried with 4.1 and 4.2 but the same issue.

    Any ideas?


  3. Hi Carl,

    Isn’t there a step missing in this. Before importing the OS layer, aren’t you supposed to export the master vm to OVF?

    Thank you!

      1. I had the same problem and a reboot resolved the problem. I spoke with Citrix support and they are aware of this issue.

  4. Carl, should the TCP Offload be disabled at the OS or Platform layer? I didn’t see that anywhere in here but I’m pretty sure it still needs to be done?

    1. If you’re putting the Target Device software in the Platform Layer then I would do it there. You usually don’t need TCP Offload disabled for other platforms.

      1. Thank you. I went back and updated my Platform Layer and updated one of my app layers. I created a new image template using the new platform/app layer and exported to PVS. For some reason now the machine is back in a work group? Do I need to rejoin the domain every time I update the platform layer and rearm?

  5. Is it a requirement for the OS layer to be non-domain joined, for example we have official company builds of OS’s which are deployed using SCCM to VSphere with VMtools and include anti-virus etc and already domain joined. For MCS masters I simply take a new built machine and install the VDA and deploy a catalog. AppDisk was simple enough to layer on top of this master base disk. So with UniDesk do we have to build a completely new clean OS from ISO without any of the company build or secuirty requirements? or can I take a build already domain joined with all security requirements and just import that as an OS layer to unidesk and then build out the application layers?

    1. I suspect either way is acceptable. It just depends on how you want to break it up.

      When you publish a template, there’s an option to run SysPrep and join the domain.

  6. Hi Carl,
    thanks for this great resource !

    When I have build my images in the past i always used the BISF script to “seal” the image. Is there still the need to do that within application layering, if yes when would you do it or does the applayer optimization script take fully care of it ?


    1. Since there are many methods of optimizing an image, Citrix doesn’t recommend the Unidesk optimization tool. It’s only KMS activation that they need. Sealing and optimizing are two different things. You might need to seal your Platform Layer.

  7. Hi Carl,

    I have a problem with the creation of the vSphere connection. My datacenter is in a folder and for this reason Citrix App Layering is not able to browse it. Is it a known limitation (I can’t find this information on Unidesk Website) ?
    I try with differents accounts (with full vSphere permissions) and I have the same results.

    Thanks for your answer.



  8. Hello Carl, Thanks for the gread documentation!

    I have published a desktop image using Unidesk. I have noticed that the Direct Access User (created by the VDA installer) group is not part od the image. I know that this is a limitation of Unidesk. Have you created it with a script? a GPO?


      1. It is created when the VDA is deployed, but it is missing when the server is publish via the template.


  9. Hi Carl, i have recently started to test with unidesk. I have implemented the ELM on our vSphere 6 Environment. Everything fine. I have created an gold image from scratch and followed your instructions. Also the creation of the platform layer was successful and i published the image at last to our PVS 7.1 environment. Unfortunately while booting the image i get a “blue screen – an error occured on your ….” I tried several times with different gold image setups, but always the same error. Do you have any guess what i may have missed?

    1. OS layer: Server2012 R2
      Platform Layer: VDA 7.12 with target device software and domain join
      no application layers

  10. Another question. When finishing up OS layer preparation, what is the correct way to handle the unattend.xml/optimizations for an MCS machine? MCS will already handle all domain operation, KMS activation, etc., but there doesn’t seem to be a way to make use of the optimizations WITHOUT using unattend.xml. The unattend.exe sets up the unattend.xml AND creates SetupComplete.cmd. SetupComplete.cmd is the script that launches optimizations.cmd, so it doesn’t look like you can use optimizations.cmd without unattend. There are a number of things that an MCS user would want from optimizations while not wanting anything from unattend (service disabling, GPUpdate forcing, etc). I was previously handling a number these things in MCS using the BISF framework.

  11. So, a few things I was unsure about or have comments on…

    1.) We are supposed to use VMXNET3, but put VMWare tools in the Platform Layer. At the same time we are supposed to patch in the OS layer which requires network access. The VMXNET3 driver is part of VMWare tools. I am just putting VMWare Tools in the OS layer because I will not using layers in anything other than VMWare, but I was wondering how to handle this to make use of this new platform layer properly.
    2.) The OS layer instructions talk about exporting to an OVF, but at the same time specify that you can import directly from vCenter. It took me a few reads to see what was going on here. Might be a little confusing to others. Maybe it should show that you can either use the OVF/SMB method OR vCenter method.

    1. 2. Oops, I forgot to remove that section. 🙂 Direct import from vCenter was added in 4.1.

      1. Install VMware Tools is the OS Layer. The Platform Layer lets you install tools for a different hypervisor, thus giving you hypervisor portability.

      1. For 2, how would you actually go about installing VMware Tools in the platform layer? I don’t have this requirement, but just curious how it would work with the VMXNET3 requirement.

        1. If you started on VMware, it’s already installed on the OS Layer.

          If you started on XenServer, you install VMware Tools on the Platform Layer. When you publish the image to VMware, ELM will remove XenTools and install VMware Tools instead.

  12. Platform Layer has been a challenge. The update machine never gets created. Failed- Description- A failure occurred while deploying the virutal machine. The error is “Cannot read property ‘$value’ of undefined’ Not much documentation on this particular error.

      1. No app layers either. I can create new OS layer. Ended up putting in a ticket. They are going to do some log collection. Seems to be related to creating a machine in VSphere. IMO.

      1. Hello,

        we’ve suspected that it might be a permission issue on the VSphere side. One of my colleagues tried to create the connector with an account which has full administrative rights on the entire VCenter environment and he managed to create the Platform Layer without any problems.

        I thought I’ll update this just in case it helps.

        I also wanted to say thanks to Carl for the great instructions.



  13. Trying to get the concept and the strength of Unidesk. Probably I miss something.
    Lets say:
    10 golden images for XenApp server. Then I can use one OS layer for all 10.
    But when I patch the OS layer and assign them to my 10 images, I have to build and publish 10 new images, that need to have a new AD insertion with new SID and I also need to update my Citrix machine catalogs with the new machines
    Thats a lot of job, more than to start 10 golden images, patch them and republish them?

    Or what am I missing in the concept?

  14. Hi Carl,

    First of all thank you for this great post.
    I have got a question for the OS Layer. Do you include RDS Feature in the OS Layer ? I ask this because, when you make an application you could need RDS feature to install the application to be compatible with a multi user environment.

    Thanks by advance for your answer.


    1. Typically RDS is included in the Platform Layer. You can also install it in an App Layer and include it as a dependent layer when creating app layers.

      1. Hello Carl! Dont get it anyway. I have ruu the “Unattend” and entered the AD information in my OS layer and when I´m done I run the “SetupComplete.cmd”(as administrator) on my golden image – it runs a lot of stuff but it dont add the machine to the ad? What am I missing?

        1. When you create the Image Template, there’s an option to run SysPrep. SetupComplete.cmd runs after SysPrep.

  15. Hi Carl….thanks for this great documentation. I have a question about step #17 – when I look at the properties of the Packaging VM that has been deployed, the disk is not Thick Provisioned, it’s showing Thin Provisioned. Not sure what caused that. Does it matter?

    1. If it’s thin provisioned, then that would be preferable to thick so you’re not consuming too much disk space.

  16. I had some issues with creating an OS Layer and had to contact Unidesk support. They told me that only MBR is supported at this time. This was for Unidesk 4.0.8. Hope this helps

    1. My suspicion is that only Basic disks are supported.

      GPT/MBR are two methods of partitioning a disk. MBR is certainly supported. Not sure about GPT.

  17. Hello! Really love your site and your work! THANKS! Saves a lot of time for us out in the field!
    I have tried to make a OS Layer Server 2016 from your instruction above but when the layer is created to 97% the next I get is “Failed to attach the disk /mnt/repository/Unidesk/OsImport Disks/Server_2016.vhd.
    Failed to probe partitions from virtual disk.”
    Any idea what could be wrong?


    1. Kent,
      Normally I hit shift+F10 when installing the OS (2016 in this case), and I go through diskpart to create/format an NTFS partition. This stopps the hidden system partition from being created. That is what I did the first time when I had the same error as you.
      The second time I did it I followed the same steps, but I didn’t format the partition in diskpart… I let the installer handle that part. Viola it worked!

Leave a Reply