Product Documentation

Install App Layering on VMware vSphere

Jan 11, 2018

When you install Citrix App Layering appliance, also known as Enterprise Layer Manager (ELM) in a VMware vSphere environment, there are four main steps:

  1. Complete the prerequisites. These includes prerequisites for installing the App Layering agent if your setup requires it. The agent enables the appliance or a Packaging Machine virtual machine to run PowerShell commands locally. When you enter the proper credentials, the agent runs PowerShell commands as a specific user. The agent is required if you use PVS, or when one of your Connector configurations opens a PowerShell script. The Connector configurations open a PowerShell script in cases in which you: 
    • Publish layered images to a provisioning system.
    • Package layers in your hypervisor environment. 
  2. Deploy the appliance installation package.
  3. Configure the network settings, such as the IP address, NTP server, and timezone. 
  4. Install the App Layering agent (optional). 

The following sections describe the preceding steps in more detail:


To install the App Layering appliance in a VMware vSphere environment, you need the following minimum prerequisites:


  • A Citrix account that includes support for App Layering.
  • A vCenter account and privileges, as described later in this section. 
  • 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.

App Layering agent prerequisites

If you plan to install the App Layering agent, you must have the following requirements on the system where you are installing the agent. 

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

For example, for version 7.6:

From a command prompt, change the directory to: c:\program files\citrix\provisioning services console
Run the following command.

Command 复制

"C:\Windows\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe" McliPSSnapIn.dll

For example, for version 7.7:

From a command prompt, change the directory to: c:\program files\citrix\provisioning services console

Run the following command.

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 Provisioning Services server.

Command 复制


VMware vSphere prerequisites

If you install the App Layering appliance in vSphere and you build your layers on vSphere VMs or you publish layered Images to vSphere, you need:

  • Network access to Tools download. You need access from the Packaging Machine VM in vSphere to the Tools download (available on the Download page).

  • vCenter account and privileges. 

    • An existing or new vCenter account to use for App Layering.
    • The account must have vCenter privileges to create and remove VMDKs, and to copy and delete layers on VMDKs by using vSphere file APIs. For details on the vCenter permissions, see the table following this list of prerequisites.
  • Dedicated vCenter role for App Layering (optional)

    To set up a new role:

    1. In the vSphere Client, navigate to Home > Administration > Roles.
    2. Click Add Role.
    3. Enter a name. For example: UDAdmin.
    4. Set the privileges for the account.
  • Privileges set for the vCenter role you're using for the App Layering service. Add the required vCenter permissions. For details on the vCenter permissions, see the table following this list of prerequisites.

    1. Open the Assign Permissions window.
    2. In the vSphere Client, navigate to Home > Inventory > Hosts and Clusters.
    3. Select your vCenter and then right-click,and select Add permission.
    4. In the Assign Permissions window, under Assigned Role, expand All Privileges.
    5. Select the permissions listed below, make sure that the Propogate to Child Objects check box is selected and then click OK..
  • The App Layering role associated with the administrator account. Associate the App Layering role with the administrator account:

    1. Add the administrator account and then assign the App Layering role to it.
    2. Allow the permissions to propagate to the entire Datacenter.

      Note: If you want to restrict this use from accessing specific folders in the Datacenter, grant the user more restrictive permissions for those folders.

  • vCenter permissions. App Layering requires vCenter-level privileges to request information about the execution status of tasks. Without those privileges, the tasks fail.

List of vCenter permissions

Expand All Privileges, and each of the following... Then select...


  • Allocate space
  • Browse datastore
  • Low level file operations


  • Create folder
  • Delete folder


  • Cancel task

Host > Configuration

  • System Management


  • Assign network


  • Assign virtual machine to resource pool


  • Export
  • Import
  • vApp application configuration

Virtual machine > Configuration

  • Add existing disk
  • Add new disk
  • Add or remove device
  • Advanced
  • Change CPU count
  • Change resource
  • Configure managedBy
  • Disk change tracking
  • Memory
  • Modify device settings
  • Remove disk
  • Rename
  • Reset guest information
  • Set annotation
  • Settings
  • Swapfile placement
  • Upgrade virtual hardware

Virtual machine > Interaction

  • Answer question
  • Configure CD media
  • Console interaction
  • Device connection
  • Power off
  • Power on
  • Reset
  • Suspend

Virtual machine > Inventory

  • Create from existing
  • Create new
  • Register
  • Remove

Virtual machine > Provisioning

  • Clone template (optional, but required to use a vSphere template as the source VM)
  • Clone virtual machine
  • Customize
  • Deploy template
  • Mark as template

Virtual machine > Snapshot management

  • Create snapshot
  • Remove Snapshot

The appliance's virtual machine

When you create the appliance's virtual machine, it will use:

  • 4 CPUs 
  • 8 GB RAM

Installation package

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

File Description


OVA file for the appliance VM


App Layering Agent installer


OS Machine Tools

Deploy the appliance

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

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

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

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

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. 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 appear.

11. Extract the download package, The files included are listed at the beginning of this topic.

12. Extract the vmware_4.x.xx.ova to a folder on your local drive.

13. In the vSphere Web Client you are using, navigate to the VMs and Templates page.

14. Right-click the folder in vSphere where you want to deploy the template and select Deploy OVF Template. The Deploy OVF Template wizard appears.

15. In the Deploy OVF Template wizard, do the following:

a. On the Select source page, select the Local file option, and browse to the vmware_x.x.x.ova file to select it.

b. On the Select name and folder page, designate a name and location for the deployed OVF template.

c. On the Select a resource page, select a location to run the deployed OVF template.

d. On the Select storage page, select the Thick Provision Lazy Zeroed setting of the Select virtual disk format option, select a storage policy, and specify a storage location.

e. On the Setup networks page, select your vSphere virtual network in the Destination column and select the IPv4 setting of the IP protocol option.

f. On the Ready to complete page, review the template settings and then click Finish when you are satisfied with the settings.

Configure the network settings

You can change the appliance's IP address and/or its DNS servers. When the appliance is first deployed, the DNS settings are retrieved through DHCP. If DHCP is not available and you will be using static IP addresses, once you select Static, you are prompted to enter the IP addresses for your DNS servers.

  1. Log in to the Appliance Configuration utility, as described above.
  2. At the Action prompt, enter C (for Configure Networking), and press Return.
  3. At the next prompt, type D for Dynamic (DHCP) or S for Static.
    If you choose Static, you will be prompted for the IP address and Subnet mask, along with default addresses for the Gateway and DNS addresses.
  4. When prompted, enter Y to save settings.
  5. At the Action prompt, enter Q to quit.
  6. Restart the appliance.

To synchonize the system clock with NTP servers

You can synchronize the system clock on the appliance by configuring NTP servers. You can specify up to six NTP servers. And, you can add and remove NTP servers, as needed. Where possible, your existing servers are used as defaults.

  1. Log in to the Appliance Configuration utility, as described above.
  2. At the Action prompt, enter N for NTP servers change, and press Return. A list of your current NTP servers is displayed.
  3. At the prompt, specify how many NTP servers you need by typing a number from 0 to 6.
    0 - All servers will be removed (you will be warned).
    1-6 - You will be prompted to accept or replace each of the current servers. 
  4. For each server, press Enter to accept the current value. Or, enter a new server address (Example: Once the last address is entered, an NTP Server Summary is displayed.
  5. Enter S to save the settings.
  6. At the Action prompt, enter Q to quit.
  7. Restart the appliance.
To change the time zone
  1. Log in to the Appliance Configuration utility, as described above.
  2. At the Action prompt, enter T for Timezone change, and press Return. The current time zone is displayed.
  3. Press Enter to display available timezones. The first bunch of time zones are displayed in alphabetical order, starting with the
  4. Advance through the timezone codes until you see yours:
    Enter - Advances one line at a time.
    Page Up Page Down - Displays the next or previous screen full of choices.
    Or search the timezones:
    Type Slash (/) and part of the name you are looking for.
  5. When your timezone is displayed, press Q to get to the prompt.
  6. Type the number for your timezone. The timezone you entered is displayed.
  7. Press Enter to complete the change.
  8. At the Action prompt, enter Q to quit.
  9. Restart the appliance.

Install the App Layering agent

The App Layering Agent installer prompts you to register the agent with an 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.

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

Locate the App Layering Agent in the installation package, or download it from the Citrix Cloud App Layering page.

Copy the Citrix_app_layering_agent_installer.exe file to a convenient location on the Provisioning Services server.

Run the Citrix_app_layering_agent_installer.exe as an 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 the prerequisites are present. If any prerequisites are missing, the installer reports this and exits without installing.

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.

The installer prompts you for the credentials (address, user name, and password) for your App Layering appliance. Register the App Layering Agent with the appliance by entering the IP address and logon credentials for a management console user on the appliance with administrator privileges, (for example, the credentials you use to log on to the management console).


If the App Layering appliance is not available 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.

Click Finish to exit the wizard.

To manually register the App Layering agent with the appliance

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

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

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.

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

Command 复制

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

When prompted, enter the password for a user who has administrator privileges in the management console on the appliance.

When the registration process finishes, a message appears informing you of the successful outcome. The App Layering Agent registration appears in the audit log for the management service.

If the process does not succeed, examine the C:\\Program Files (x86)\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:

Command 复制

Citrix.AppLayering.Agent.Service.exe /?