Product Documentation

OS layer

Jan 11, 2018

The OS layer is a virtual disk attached to a virtual machine running the supported Windows Operating System that you want to use for your Layered Images.

This topic explains how to prepare a clean OS image for layering, and then import the image into a new OS layer. Once created, you can use the OS layer to build as many App layers, Platform layers, and Layered Images as you need.

Before you start

  • Start with a fresh operating system image, preferably from your hypervisor, in this case, Azure. This is so that the operating system is partially optimized for your environment.
  • Make sure that the OS Image is not in a domain, and that it gets its IP address from DHCP.
  • Ensure that the virtual machine for your OS Layer is MBR partitioned, rather than GPT partitioned. Otherwise, you will not be able to install the Citrix App Layering OS Machine Tools.
  • Using Third-party optimization scripts can have adverse effects for layering, as they can change services and features that the App Layering service uses, for example, Universal Plug and Play and the 8.3 file names setting. Use the optimization tools in the Installer download to optimize your image.

Prepare a Windows Server 2016 or Windows Server 2012 R2 image

Create an OS Machine in Azure

  1. In the Microsoft Azure portal, create a new VM from the Windows Server Remote Desktop Session Host Windows Server 2012 R2 image (New > Compute > Virtual Machine > From Gallery > Windows Server Remote Desktop Session Host Windows Server 2012 R2).
  2. Choose Resource Manager from the Select a deployment model option list and click Create.
    Note: The App Layering software does not support the Classic option from the Select a deployment model option list.
  3. Complete the Create virtual machine wizard to create the OS machine.
  • The name of the new server machine you specify must comply with Azure naming conventions.
  • The User name and Password of the new server machine you specify becomes the User name and Password of any Packaging Machines that are subsequently created containing this OS Layer.
  • Be sure that the value for the Resource group location matches the Storage account location that you configured in the Platform Connector Configuration.

Prepare the image

To prepare the image:
  1. After the new server machine has been successfully created, reboot the machine, and log into it remotely.
  2. Turn off Windows Automatic Updates (Control Panel > System and Security > Windows Update > Change Settings).
  3. From the new machine, open a web browser, navigate to the Download Center and download the OS Machine Tools.
  4. Rename or delete the "Unattend.wsf" file in the C:\Windows\OEM directory.
    Note: Do not use the Unattend.exe, as this is not needed and will cause issues with Azure.
  5. On the new server machine, run the setup_x64.exe file to install the App Layering drivers on the OS Machine.
  6. Ensure that this machine is not joined to a domain.
    Note: Session Hosts will join a domain when you provision them from a Layered Image.
  7. Optionally, you can shut down the new OS machine.


  • Before you can import the OS Disk (as described in the following section), the state of the OS Machine must be either Stopped, Stopped (deallocated), or Running. The OS Disk can only be imported if the OS machine is in a Starting or Updating state.
  • You must perform any pending reboots to the OS machine before importing the OS Disk.

Once you have completed these steps, you are ready to create an OS Layer.

Import the OS image into a new OS layer

In the Management Console, select Layers > OS Layers and click Create OS Layer in the Action bar. This opens the Create Operating System Layer Wizard.

In the Layer Details tab, specify a Layer Name and Version, both required values. Optionally, you can enter Descriptions of the Layer and Version, and change the Max Layer Size to accommodate the OS you are going to import. For details, see more about these values below.

In the Connector tab, choose a Connector Configuration for the platform where you'll be publishing your Layered Images. If the configuration you need is not listed, add a New one and select it from this list. For information about creating a new Connector Configuration, see Create a Connector Configuration.


Note: Alternatively, if you have a *.vhd file of the OS disk in your File Share, you can select the file share instead of an App Layering connector.

In the Import Disk Details tab, enter the name of the Azure Resource Group that contains the OS disk and the name of the OS disk, both required values.


If you specified a file share on the Connector tab, enter the name of the OS disk residing on that file share or click Browse to select it.

In the Icon Assignment tab, select an icon image to assign to this layer.

In the Confirm and Complete tab, review the details of the OS Layer, enter a comment if required, and click Create Layer. If you enter comments, they appear in the Information view Audit History.

When the task completes, the new OS Layer in the Management Console displays a "Deployable" status.