Create and update OS Layer – Citrix App Layering

This post describes the actions taken to create an OS Layer in Unidesk (Citrix App Layering) 4.x running on Hyper-V with Citrix PVS. You are also shown how to add new versions to the OS Layer for the purpose of patching, upgrading and making changes to the OS Layer image. Here you will see how the Platform Layer and Image Template plays a key part in packaging and deploying Unidesk OS Layers.

To create an OS Layer, you must have the Unidesk ELM (Enterprise Layer Manager) appliance installed. Read

This guide deploys an OS Layer using Unidesk on Hyper-V. For VMware instructions, see Carl Stalhood’s Unidesk OS Layer and Platform Layer post.

When adding a version to your OS Layer you must package the layer on the same Hypervisor from which you imported the OS during layer creation. This isn’t the same as packaging Application Layers. Application Layers can be packaged on any supported Unidesk Hypervisor of your choice so long as you are using a Platform Layer for packaging with the correct hypervisor tools installed to support the application installation.

Other points to note when creating an OS Layer:

  • .NET Framework 4.5 must be installed on any layered image when Elastic Layers are used on top of that layer.
  • Do not use periods in the image filename when using PVS.
  • You must disable IPv6 in the OS Layer when using PVS. Do not disable in the Platform Layer. Also, disabling IPv6 by unchecking the option within network adapters isn’t good enough. You must actually disable IPv6 using the Registry in the OS Layer to ensure new network interfaces used with Target Devices automatically have IPv6 disabled on them. I show how to do this further down the post. If you created a Platform Layer before disabling IPv6 in the OS Layer, you must create a new Platform Layer after IPv6 is disabled in the OS Layer.
  • UEFI is not supported for the OS Layer. This is because the OS Layer must be partitioned with MBR rather than with GPT (not supported). In our case, we are using PVS with Hyper-V. That means, you cannot build the OS Layer using a Generation 2 Virtual Machine. You must use a Generation 1 machine. To boot in to PVS, you must then use the Legacy NIC to boot in to a Gold Image regardless if the bootstrap is delivered by BDM or TFTP. Your Target Devices should also contain a Synthetic NIC to take over streaming once the Target Device has booted. See for more information.
  • When using Hyper-V to create the OS Layer, use a machine with one Legacy NIC when building the OS Layer. I have found that not doing this results in a BSOD when booting to the published vDisk.
  • Make sure your PVS Target Device hardware settings match those set in the OS and Platform Layer hardware settings. If the number of CPUs in your Target Device VMs are larger than what was used during OS Layer creation for example, you may get a reboot required message when the published image is booted.
  • If using App-V 5.1 with Unidesk 4.0.8, you may encounter BSODs on the VDA. There seems to be a conflict between the unifltr.sys and AppvStrm.sys mini-filter drivers. Upgrade to 4.1 or above which contains the required hotfixes.
  • You cannot install the OS Layer on any drive other than C:\.

♣ Creating the OS Layer Gold Image
♣ Importing the OS Layer in to ELM
♣ Creating a Platform Layer
♣Creating an Image Template
♣ Updating the OS Layer

Creating the OS Layer Gold Image:

To begin using Hyper-V create a Virtual Machine as Generation 1.

Ensure the machine is configured with a Legacy Network Adapter. You should not configure any other network adapters on the machine. Install a supported Operating System. You should also fully patch the OS with Windows Updates.

As we are using PVS it is important that you disable IPv6 by opening RegEdit and navigating to HKLM\System\CurrentControlSet\Services\TCPIP6\Parameters. Create a REG_DWORD value with a name of DisabledComponents and a value of 0xFF.

Another requirement is to disable Automatic Updates which can be done via gpedit.msc on the local machine using Local Group Policy Editor.

Extract unidesk_os_machine_tools_4.0.8 from the Unidesk download media.

Click InstallThe containing files are extracted to C:\Windows\Setup\Scripts\.

Navigate to the extracted location and run setup_x64.

Click Next.

Since we are using PVS there is no need to use an answer file. Click Next.

Click Finish.

At this stage you should be ready to convert the Operating System you have just prepared in to an OS Layer. Copy the VHD file to the ELM Share that is used by the ELM appliance.

Importing the OS Layer in to ELM:

Log on to the Unidesk Management Console and navigate to Layers -> OS Layers -> Create OS Layer.

Specify an appropriate name, description, version and maximum layer size. The layer disk will be thin provisioned.The connector that points to your ELM Share should already be configured. If not, you’ll need to create one. Select the ELM Share connector and continue. For information on creating an ELM Share see

Click Browse.

Expand the ELM share and select the VHDX file to be used for your gold image. Click Choose.

Now click the down arrow.

Specify an icon for the OS Layer. You can also upload icons.

Review the settings and click Create Layer. A Creating OS Layer task begins which you can view the details of. This task imports the VHDX you specified in to the ELM Appliance.

Once complete the OS Layer status is set as Deployable. The Creating OS Layer task also reports as done.

Creating a Platform Layer:

The next step involved is to create a Platform Layer. The Platform Layer consists of the hypervisor tools, VDA tools and PVS Target Device software. Within the UMC, navigate to Layers -> Platform Layers -> Create Platform Layer.

Specify an appropriate name, description, version and maximum layer size.

Choose the OS Layer you just imported. The Platform Layer is created based off the OS Layer.

Choose the ELM Share connector. Currently there is no way for the ELM Appliance to automatically provision a Packaging Virtual Machine. If using VMware or XenServer etc. the ELM appliance can create a Packaging VM for you. The Packaging VM is what you use to boot in to the Platform Layer and install the necessary tools. In previous versions this VM was called an Installation Machine. For Hyper-V, the ELM appliance creates the Platform Layer VHDX files on the ELM Share and we manually create a Packaging Machine.

There are two types of Platform Layers you can create. One for packaging layers and one for publishing layers. Since we are publishing a layer, we can select the second radio box. Specify Microsoft Hyper-V for Hypervisor, Citrix PVS for Provisioning Service and Citrix XenDesktop or XenApp for Connection Broker.

You can change the disk format and disk filename if you wish, if not, continue on.

Pick an icon or upload one yourself.

Click on Create Layer.

The Platform Layer creation task begins with the install disks copying to the ELM share.

Once the disks are copied you’ll be presented with a message telling you where the disks are located. We are dealing with two disks here, so we will create a Packaging VM and attach the two virtual disks.

Create a new virtual machine with a name related to packaging.

Specify the machine as Generation 1.

Choose to use an existing virtual hard disk and click Browse.

Browse to the ELM Share\Unidesk\Packaging Disks. Inside this directory you will find the two disks. Firstly attach the boot disk.

Secondly attach the package disk.

Note: In terms of network adapters, you can safely use a Synthetic NIC.

Power on the VM.

Install Hyper-V Integration Services.

Click Yes to restart. It is safe to restart as many times as you like. Once restarted join the machine to your domain.

To install the Target Device software, launch the PVS media and click Target Device Installation.

Once the install is complete click Finish.

Reboot the machine again.To install the VDA software launch your XenApp & XenDesktop media. Select Create a Master Image. Uncheck Citrix Receiver. Receiver should be installed as an Application Layer. Unselect Optimize Performance. Uncheck/check any other components you need.

Click Close to restart

Eventually the VDA installation will complete. Click Finish. The machine will restart for the last time. You should now make all necessary optimizations to the gold image by disabling unneeded scheduled tasks and services etc. See for pointers and if using Windows Server 2016 see Unidesk/Citrix and VMware have optimization tools that allow you to hand pick common optimizations for VDI and SBC machines. The Unidesk/Citrix optimization tool is found within the Unidesk Gold Image Tools file.

Now that all the required tools are installed and optimisations are completed within the Platform Layer we can finalize the disk. To do so, you must run Shutdown For Finalize which is located on the Packaging Machine’s desktop.

The Shutdown For Finalize tool runs a quick integrity check to ensure no pending operations are queued. In this case as you can see, an NGen operation is still in progress so the layer finalization does not proceed.

To check the progress of NGen, you can monitor the ngen.exe service. Once it dissapears you will be able to finalize the image.

Alternatively you can run ngen update /force to force a regeneration of native images.

Once the compiles are complete, you can finalize the image. The Packaging Machine will be shut down.

Take a copy of the two virtual hard disks within the Packaging Disks folder.

Paste the disks in to the Finalize Disks folder within the ELM Share directory.

Return to the UMC, select the Platform Layer and click Finalize.

Click Finalize.

The disks will be imported into local storage on the ELM Appliance.

The disk contents are being converted into a layer.

The Platform Layer has been successfully created.

The Platform Layer now shows as deployable.

Creating an Image Template:

Finally to publish the OS Layer out to PVS we need to create an Image Template. Image Template’s bundle the OS Layer, Platform Layer and any Application Layer together. It is when you are publishing an Image Template that all these different layers are merged together to create a desktop for end user consumption. In the UMC, navigate to Images -> Create Template.

Note: At any time you can edit an Image Template and assign/remove Application Layers and so on.

Enter an appropriate name and description. Select an icon or upload your own.

Select the only available OS Layer recently created.

No Application Layer’s are available at the moment so we can continue on. When we have an Application Layer available we can come back and edit this Image Template to include the layer.

Rather than have ELM publish the image to the ELM Share, instead we want the ELM Appliance to publish the image out to PVS. Click on New.

Note: You could publish the image to the ELM Share and manually import in to PVS, however it is a manual approach.

Underneath Type, there are several connectors available to create such as MCS, PVS, Nutanix, XenServer. Click on Citrix PVS.

Now click New.

A new popup appears. Make sure your popup blocker is not interfering. The popup webpage directs you to a PVS Connector creation screen. Underneath Console use the dropdown to select your PVS server. Any PVS server that you have successfully installed the Unidesk Agent on and registered with ELM will appear here.

Note: A quick tip – Install Unidesk Agent’s on “master” PVS servers, ones that you normally nominate to perform all changes on. This server must also have the PVS Console installed.

Enter service account credentials that has Farm Administrator rights on PVS. Click Check Credentials and wait for the The credentials have been verified message. Now that credentials have been provided the PVS farm is quried for the Site Name, Store Name(s) and so on. Select the appropriate details as below. In terms of Write Cache and License Mode etc. Unidesk will import the published image in to PVS and automatically configure these settings on the vDisk for you. Click Test.

Note: You could publish all images to a staging store for example, then move them to their appropriate stores afterwards. You can also create multiple connectors, so one for VDI machines and one for Session Host machines with different Write Cache sizes. Enter a Configuration Name (at the top of page) and then click Save. 

You should receive a These settings were successfully saved message.

Returning back to the Unidesk Management Console you’ll see your newly created PVS Connector. Highlight it, then click the down arrow.

Choose the only available Platform Layer. This layer is layered in to the OS Layer image.

Specify an appropriate name and layered disk size. The disk size is thin provisioned. If you are using Elastic Layering, choose Application Layers Only. This installs a Unidesk Layering Service inside the image and prepares the image for Elastic Layering capabilities.

Click Create Template.

The new Image Template shows underneath as publishable. You now have to publish the image out to PVS. Click Publish Layered Image.

Note: You can highlight and publish multiple Image Templates at once. Unidesk will publish up to 4 concurrently.

Click Publish Layered Image.

A new task begins for publishing the image.

At this stage the image is transferring to the PVS store.

As you can see on the PVS Store a .tmp file is placed in the directory which will later become the published vDisk.

Image is registering with PVS.

The published job is complete and we should now have the image in PVS.

Within the PVS Store we can now see the vDisk and relevant .lok and .pvp files.

The vDisk also appears in the PVS console, configured with Cache in Device RAM with Overflow to Hard Disk. Create some Target Device VM’s and boot in to the image to confirm everything is in place.

The PVS Target Device software and VDA is present. The Hyper-V tools are also installed but just do not show in Add/Remove Programs. The image also successfully registers with the Delivery Controller. You’ve successfully created your first OS Layer in Unidesk!

Updating the OS Layer:

When the time comes, you’ll eventually need to add versions to the OS Layer image to make changes. The majority of times you’ll only need to perform Windows Update patching on the OS Layer image as generally most applications will be in separate Application Layer’s which come with their own versions. When you create an OS Layer version, the existing latest OS Layer is copied and marked as read/write. You then use a Packaging Machine to boot in to the read/write layer and make the required changes to the image.

To create an OS Layer version navigate to Layers -> OS Layers -> select the OS Layer and -> Add Version.

Enter a new version number, description and max layer size. The Max Layer Size value should be large enough to host the OS Layer and any updates you are performing. 

Choose the ELM Share connector. The new published OS Layer version will be created here. You then attach the disk to a Virtual Machine and perform any patching before finalizing the disk.

Specify a packaging disk filename and disk format. You’ll likely keep the defaults.

Click Create Version.

The new versioned disk is created within the ELM Share, ready to be attached to a Packaging Virtual Machine.

Locate the virtual disk and attach it to a Virtual Machine. Use a Virtual Machine which has the same hardware configurations as your Target Device VM’s. Make sure the Virtual Machine is configured with a Legacy NIC, and do not add any additional NIC’s to the machine.

During the Platform Layer optimizations Windows Update was disabled, a Unidesk and general VDI/SBC requirement. You must temporarily start the Windows Update service.

Also set Automatic Updates to Enabled. Make sure to turn these off again after patching.

Search for and install patches.


Reboot the Packaging VM to finish installing updates.

When the machine is back up log on and run the Shutdown For Finalize tool.

Copy the OS Layer to the Finalize Disks folder in the ELM Share.

Return to the Unidesk Management Console, select the OS Layer and click Finalize.

Click Finalize to finalize version 2 of the OS Layer.

At this stage the new OS Layer version will be imported in to the ELM local storage.

The new layer version is ready to be used.

To publish the new layer version out to PVS you need to edit your existing Image Template to include the new OS Layer version. Navigate to Images -> click on the relevant Image Template and select Edit Template.

Navigate to the OS Layer tab and then expand the OS Layer, selecting Version 2.

Click Save Template Changes.

Now go through the Publish Layered Image wizard to publish the disk to PVS, attatch to Target Device VM’s and power them on.

Confirm the new OS Layer version is in effect by looking for the updates you just installed.

That’s it. You have just successfully updated an OS Layer in Unidesk!

To create Application Layers and Elastic Layers, see

Known Issues

  • When adding a version to your Windows 10 layer to perform an upgrade, change the Max Layer Size from 30GB to 60GB.
  • Windows 10 sometimes creates a Recovery Volume as a new partition on the same disk as the OS Layer version. This volume needs to be removed before the finalize the OS Layer version. This is because the Recovery Volume can cause boot failures.


  • Pingback: Detailed Change Log – Carl Stalhood

  • Pingback: Unidesk OS Layer and Platform Layer – Carl Stalhood

  • Pingback: EUC Weekly Digest – February 4, 2017 – Carl Stalhood

  • Pingback: Site Updates – February 2017 – Carl Stalhood

  • Tyson Glaser

    April 14, 2017

    If you were going to XenApp hosts and want to do write cache with overflow to disk you need to attach a second hard drive and move everything over to that drive (page file, event logs, ect) and it needs to exist for the RAM to be able to overflow on to. Should this be done on the platform layer or the OS layer?

    • George Spiers

      April 14, 2017

      Hi Tyson. You don’t create a second disk within any layer as such. The persistent disk is separate from layers. Once you have an Image Template and it is published out to PVS or MCS, you create machines and each machine has a disk attached that is used for the Write Cache, Pagefile, Event Logs like you mention.

      • Tyson Glaser

        April 17, 2017

        But the image you create doesn’t have the new attached initialized/configured on boot so the page file/cache/event logs don’t move. Do you have to boot the Image Template up into private mode first and configure the attached disk before setting it back to standard and booting up the other machines to the vDisk? If that’s the case, wouldn’t you have to do that step every time you update the OS or Platform layer creating a new Image Template?

        • George Spiers

          April 18, 2017

          When you create machines via PVS, use the XenDesktop Setup Wizard. You pick a size that the local write cache will be. When the PVS machines are created and booted, they’ll be configured with a WCDisk disk likely to be letter D:\ or the next free letter on your OS. The Write Cache and Pagefile will be on the WCDisk. To move Event Logs, you make the required registry edit on the OS Layer to point them to D:\.

  • Tyson Glaser

    April 17, 2017

    Also, for something like Workspace Environment Manager where I need to have the WEMCache on the attached disk how would I go about doing that at the App layer? If I create the app layer and load the OS layer in the packaging VM, the attached disk does not exist like it would on a PVS machine so there’s no way to configure that?

    Maybe I’m not understanding this product as a whole like I should be, but to me, it seems like it would be easier to just build a single PVS vDisk with all the needed applications in Private mode, then change the disk to standard and publish it out to the VMs. If I have to change the vDisk to private mode to reconfigure the attached disk every time I do an image template for a a new App, OS update, or Platform update that seems like more work than just updating a vDisk in private mode? Am I looking at this the wrong way or something?

    • George Spiers

      April 18, 2017

      When installing the WEM Agent, you don’t need the disk configured on the Packaging VM. You can install the WEM Agent, specify that the cache exists on D:\WEMCache for example and the Agent will install regardless if D:\ is actually present or not. Now when you publish the image out to PVS, the D:\ drive will exist if you use the XenDesktop Setup Wizard as it creates the disk drive for you. You don’t need to put vDisks in to private/maintenance mode or perform repetitive drive configurations so yes you are looking at this the wrong way.

  • Matt Russell

    May 1, 2017

    George – Do I need to add the other NIC for PVS stream to the VM in a layer or add it to the server once the image is build/deployed to PVS? Seems like the server would want a restart after adding the NIC.

    • George Spiers

      May 1, 2017

      Just add the second “Synthetic” NIC to your VM Templates that PVS uses to deploy machines. You don’t need to add it to a layer.

  • Matt Russell

    May 8, 2017

    George – Where would UPM be installed? I’d assume as an app layer that’s assigned to the OS layer in use, but hoping you might have practical knowledge here. Thanks again!

    • George Spiers

      May 8, 2017

      If you are referring to Citrix Profile Manegement, it is installed on the Platform Layer alongside the VDA. If it’s another UPM solution, you can install it on an App Layer.

  • Chone P.

    May 8, 2017

    How to do install WEM agent when utilizing MCS and App Layering?

    • George Spiers

      May 8, 2017

      Install WEM Agent in App Layer. Use the command line to install the Agent using the AgentCacheAlternateLocation and AgentServiceUseNonCompliantHistory switches. The Agent cache should be redirected to a persistent drive.

      • Chone P.

        May 9, 2017

        That part is understood when using PVS and redirecting to the write cache during the XD wizard target device creation, but when using MCS it creates a hidden identity disk when it creates a catalog. Do we need to provision a secondary persistent disk to each MCS target device to acheive the same results as with PVS?

        • George Spiers

          May 9, 2017

          Yes correct.

  • Adil

    August 7, 2017

    Thank you very much George for your usual help
    I follow this nice article, with a difference, that I work with vsphere, and I got to the creation of pvs connector
    I can not configure the pvs connector I installed the Citrix App Layering Agent on the pvs server During installation I get an error: “a failure occured whene executing ‘netsh’” Error Adding Certificate I put ok and the wizard finishes installation just after 1. I removed security on PowerShell 32 and 64 on the pvs server Set-ExecutionPolicy Unrestricted 2. I executed the EML registration command on the pvs server successfully Citrix.AppLayering.Agent.Service.exe register / i / e: IP_address_of_ELM / u: Domain \ Administrator 3. I also run the commands below: From a command prompt, go to: Cd “c: \ program files \ citrix \ provisioning services console” C: \ Windows \ Microsoft.NET \ Framework64 \ v4.0.30319 \ InstallUtil.exe McliPSSnapIn.dll C: \ Windows \ Microsoft.NET \ Framework64 \ v4.0.30319 \ InstallUtil.exe Citrix.PVS.snapin.dll 4. I activated the remote powershell on Powershell 32 and 64 Enable-PSRemoting When I create a new pvs connector, and I check the connection, the system returns the following error message: One or more the pvs configuration is invalid, please check your selections And set the field red: Console And the following message: Citrix App Layering Agent Error: Error: read ECONNRESET
    Your help please.


Leave a Reply