Product Documentation


Jan 11, 2018

Before you start

To install the appliance in Hyper-V environment you need the credentials for the server on which you want to install the appliance, storage space for the appliance and the layers and images you create, along with the other prerequisites listed below.

Hyper-V prerequisites

Ensure that the Hyper-V virtual machine from where you are installing the appliance meets the following prerequisites:

  • Windows Windows Server 2016, Windows Server 2012 R2, or Windows Server 2008 R2
  • Virtual network in Hyper-V

Storage requirements

  • 350–500 GB Storage Space
    The App Layering appliance uses local storage for temporary files and finalized layers. The more layers you create, the more space you need. However, if you run low on space, you can expand the size of the current disk, or add other disks to the appliance when needed.

  • 40–100 GB network file share (SMB)
    The file share connected to the appliance is used for upgrades, Elastic Layers, and cross-platform publishing. This space is easy to expand, if needed.

Operating system requirement

  • Operating system for layered images

    You need a supported operating system freshly installed from ISO, to use in your OS layer. The OS layer is used to build all your other layers and layered images. Preferably, import the ISO from your hypervisor so that the operating system is partially optimized for your environment.

Installation package

The installation package, citrix_app_layering_hyperv_4.x.x, includes:

File Description

VHDX files for the appliance VM


App Layering Agent installer


OS Machine Tools

Virtual appliance details

Name Value

Virtual Machine Name

App Layering Appliance (Enterprise Layer Manager)

VIrtual Machine Generation

Generation 1


8192 MB



Disk 1


Disk 2


Deploy the App Layering appliance

  1. Log in to the Citrix Cloud. A Citrix App Layering tile should be displayed at the bottom of the page.

  2. On the Citrix App Layering tile, click Request Trial, and check your email for a message from Citrix Cloud.

  3. In the message you received, click the Sign In button. This returns you to

  4. Click Manage on the App Layering tile. The Citrix App Layering page is displayed.

  5. Get familiar with the service by reading the Overview. When ready, click the Get Started button to open the Getting Started tab.

  6. Under Step 1, click the Get Cloud Connector button, and for instructions click the Documentation link.

  7. Use the Connector documentation to install a Cloud Connector, then return to the Getting Started tab.

  8. At the top of the page select the hypervisor where you are deploying the App Layering service. This selection determines which platform-specific installation package will be downloaded in Step 2.

  9. Under Step 2, click the Download for Hypervisor button to download the appliance installation package for the hypervisor you have selected.

  10. Under Step 3, right-click Instructions, open the page in a new browser tab, and select your hypervisor. The installation instructions for your hypervisor are displayed.

  11. Extract the download package, Two disk (vhdx) files are included.

  12. Copy the disks to a storage location that Hyper-V can access.

  13. Open the Hyper-V Manager, right-click the Hyper-V server where you want to deploy the appliance, and select New Virtual MachineThis opens the New Virtual Machine Wizard.

  14. On the first wizard tab, click Next to begin configuring the virtual machine.

  15. On the Specify Name and Location tab, set the Name and Location of the new VM. Ideally, use the location where you extracted the disks in step 2.

  16. On the Specify Generation tab, ensure that Generation 1 VM’s is selected. Generation 1 only is supported.

  17. On the Assign Memory tab, set the VM to use 8 GB of RAM. Make sure the Use Dynamic Memory for this virtual machine check box is not selected.

  18. On the Configure Networking tab, specify the NIC for the network adapter to use to connect to the network.

  19. On the Connect Virtual Hard Disk tab, attach the system disk (unidesk_hyperv-system.vhdx), one of the disks that you extracted in step 2.

  20. On the Summary tab, verify your choices and click Finish.

  21. Back in the Hyper-V Manager, select the VM and click Settings from the VM panel.

  22. Select Hardware > Processor, and set the Number of Virtual Processors to 4.

  23. Select IDE Controller 0 > Hard Drive, click Add.

  24. Select the Virtual Disk radio button, click Browse, and select the repository disk (unidesk_hyperv-repository.vhdx) extracted in step 2.

  25. Power on the VM.

  26. Back in the Cloud, under Step 4, the Documentation link opens the instructions for logging in. (The link below opens the same article.)

  27. Click the Log into Appliance button. This opens the Manage tab. Follow the instructions (link below) to log into the appliance.
    The installer prompts you for the credentials (address, user name, and password) for your App Layering appliance. 

  28. Type the IP address and logon for an administrator with permission to access the App Layering management console.

The first time you log onto the appliance you are required to change the App Layering administrator passwords, For details, see Change administrative passwords

Be sure to install the App Layering Agent, if your environment requires it. See the next section for details.

Install the App Layering Agent

The App Layering Agent enables the App Layering appliance (Enterprise Layer Manager) or a Packaging Machine VM to run PowerShell commands locally. If you supply the proper credentials, the agent can run PowerShell commands as a specific user.

The App Layering Agent is required in cases where one of your Connector Configurations launches a PowerShell script. This includes Connector Configurations you use to:

  • Publish Layered Images to a provisioning system.
  • Package Layers in your hypervisor environment.

The App Layering Agent installer prompts you to register the agent with a App Layering appliance. If you do not register the agent during installation, you can manually register it later. However, keep in mind that the PowerShell scripts will not run until the agent is registered with the appliance.


Before you install the App Layering Agent, you must have the following requirements on the system where you are installing the App Layering Agent:

  • An account with administrator privileges
  • .NET 4.5
  • PowerShell 3.0 or greater
  • PowerShell Snap-in
    Before using the App Layering Agent on a PVS server you must ensure the PowerShell Snap-in is installed. This is a manual step.
    • For PVS 7.7 and later, you must install the Powershell Snap-in Citrix.PVS.Snapin.dll.
    • For PVS 7.6 and PVS 7.1, you must install McliPSSnapIn.dll. Use the installutil.exe to install the Snap-in.

Example (7.6):
From a command prompt, go to: c:\program files\citrix\provisioning services console
Run this command: "C:\Windows\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe" McliPSSnapIn.dll

Example (7.7):
From a command prompt, go to: c:\program files\citrix\provisioning services console
Run this command: "C:\Windows\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe" Citrix.PVS.snapin.dll

On Windows 2008 R2, you must also enable PowerShell remote commands. For background information, see this Microsoft article:

If your 2008 R2 OS does not have PowerShell remoting enabled, run the following PowerShell command on the PVS server: Enable-PSRemoting  

Install the App Layering Agent

  1. Log in as an administrator on the system where you are installing the agent.

  2. Locate the App Layering Agent Installer in the installation package.

  3. Copy the citrix_app_layering_agent_installer.exe file from the App Layering Agent folder to a convenient location on the server where the agent is required.

  4. Run the citrix_app_layering_agent_installer.exe as Administrator, and when prompted, enter the path to the directory where you want to install the App Layering Agent. The default location is C:\\Program Files (x86)\Citrix\Agent.

    The App Layering Agent installer checks to see if all Prerequisites are present. If any prerequisites are missing, the installer reports this and exits without installing.

  5. The installer prompts you for an Agent Port number. You can accept the default port number (8016) or specify a different one if the default port is already in use.

  6. The installer prompts you for the credentials (addressusername, and password) for your App Layering appliance. Register the App Layering Agent with the appliance by entering the IP address and login credentials for a Management Console user on the appliance with Administrator privileges, (for example, the credentials you use to log into the Management Console).

    Note: If the App Layering appliance is not available yet or you choose not to register with it now, you can manually register at a later time using the procedure described in Register with the App Layering appliance manually.

  7. Click Finish to exit the wizard.

The App Layering Agent registration appears in the Audit log for the Management Service in the Management Console.

Register with the App Layering appliance manually

If the App Layering Agent was not registered with a App Layering appliance during installation, you can register it later by using the following procedure.

To manually register the App Layering Agent with the appliance:

  1. As an administrator, log in to the server where you installed the App Layering Agent.

  2. Open a command window (cmd.exe) as administrator and navigate to the directory where the App Layering Agent is installed. (The default location is C:\\Program Files (x86)\Citrix\Agent\.)

  3. Run the following command, using the IP address of the appliance where indicated:

    Citrix.AppLayering.Agent.Service.exe register /i /e:Appliance_IP_address /u:Administrator

  4. When prompted, enter the password for a user who has Administrator privileges in the Management Console on the appliance.

  5. When the registration process completes, a message appears informing you of the successful outcome. The App Layering Agent registration appears in the Audit log for the Management Service in the Management Console.

If the process does not succeed, examine the \Citrix\Agent\Logs\applayering.agent.log file in the App Layering Agent installation directory. You can also view Help for the App Layering Agent command line options by running the following command: Citrix.AppLayering.Agent.Service.exe /?.