App Layering

Citrix Hypervisor

You can use your Citrix Hypervisor environment for creating Layers, and for publishing layered images. Each Connector Configuration accesses a specific storage location in your Citrix Hypervisor environment. You may need more than one Citrix Hypervisor Connector Configuration to access the correct location for each purpose. Further, you can publish each layered image to a location convenient to the system you provision with the published image. For more about Connectors, and Connector Configurations, see Connector configurations.

The Citrix Hypervisor architecture allows you to interact with individual servers or cluster of servers instead of a central management server. You manage Citrix Hypervisor by using command-line access or management software, such as XenCenter. You install XenCenter on your desktop and connect individually to each host or to a cluster of hosts.


Citrix Hypervisor does not support UEFI-based machines.

First time using Citrix App Layering appliance If you want to create App Layers by using a Citrix Hypervisor virtual machine, you need a Citrix Hypervisor Connector within App Layering. When publishing layered images to Citrix Hypervisor, you also need a Connector Configuration for each of your publishing locations.

Creating a layer and publishing a layered image prompts you to select a connector configuration. If you don’t yet have the right connector configuration for the task, you can create one by clicking Add Connector Configuration on the Connectors page.

Required information for Citrix Hypervisor Connector Configuration settings Configuring a connector for Citrix Hypervisor lets you browse for the XenCenter Server, Data Store, and Host to use for a new configuration.


The fields are case sensitive. Any values that you enter manually must match the case of the object in Citrix Hypervisor, or the validation fails.

  • Citrix Hypervisor Configuration Name - A useful name to help identify and keep track of this connector configuration.
  • Citrix Hypervisor Address - The name of the Citrix Hypervisor host with which the appliance integrates.
  • User Name and Password - The credentials for the account that the appliance uses to connect to Citrix Hypervisor.
  • Use Secured Communications - Use SSL encryption for the API connection traffic between the App Layering Connector and Citrix Hypervisor. This field is checked by default.
  • Ignore Certificate Errors - Enables certificate errors to be ignored. By default, this setting is disabled.
  • Virtual Machine Template - The virtual machine template that you can use for cloning. The list of choices contain custom virtual machine templates only, rather than actual virtual machines or any of the built-in templates. The selected template must not have any disks attached, and must have at least one network card attached. If it does not, you see an error when trying to validate or save the configuration.
  • Storage Repository - The storage repository for the disk that uploads. The list is filtered to show only repositories that can contain virtual hard disks (ISO repositories are filtered out).
  • Layer Disk Cache Size in GB (optional) - Specifies the size of the cache allowed for the layer.
  • Use HTTPS for File Transfers - Encrypts the image file transfers. HTTPS is checked by default for more secure uploads and downloads, but can be unchecked for increased performance.

Virtual Machine organization Virtual machines created by the Citrix Hypervisor connector, whether packaging machines or layered images, can use either folders or tags to organize the virtual machines. Citrix Hypervisor allows you to organize virtual machines by folder or by tag. These organizational tools are optional when creating and managing virtual machines through XenCenter or other tools. Although Citrix Hypervisor connector configurations do not allow you to specify folders or tags, the virtual machines created by the Citrix Hypervisor connector, both packaging machines and published layered images, can utilize both organizational tools.

Caching Tags If the template specified in the Citrix Hypervisor connector configuration has any tags, then those tags are carried over to any virtual machine cloned from that template. All packaging virtual machines or published layered images are tagged with the same tags that the template has. Additionally, the Citrix Hypervisor connector adds three tags.

  • App Layering - All virtual machines created by the Citrix Hypervisor connector can be found by this tag regardless of their purpose or image.
  • Purpose Tag - All packaging machines are tagged with App Layering Packaging Machine while all published layered image virtual machines are tagged with App Layering Published Images.
  • Image or Layer Name - All packaging machines are tagged with the layer name for the layer for which they are generated, while all published layered images are tagged with the template image name. If you are using XenCenter, you can view your virtual machines by tag by selecting the “Organization Views” and then select “By Tag”.

Folder By default virtual machines created by the Citrix Hypervisor Connector are not placed in a folder. However, if the template specified in the Citrix Hypervisor Connector Configuration resides in a folder, then any virtual machine that the Connector creates from that template also resides in the same folder. All packaging VMs and published layered images will be placed in that same folder. There will not be separate subfolders for packaging VMs or published layered images.

Machine network connectivity The virtual network settings of the source template specified in the Citrix Hypervisor Connector Configuration will be carried over when creating any VMs through the Citrix Hypervisor Connector. There is no option in the Connector Configuration UI to override the network settings.

Citrix Hypervisor Clusters The Citrix Hypervisor Connector does not yet work correctly with Citrix Hypervisor clusters. If the host specified in the configuration is part of a cluster, then it must be the master host in the cluster for the connector to work. However, this means that any time the master Citrix Hypervisor host goes down and a new master is elected, the Citrix Hypervisor configuration must be updated.

Scripts The Citrix Hypervisor Connector supports script execution after publishing layered images just as the vSphere connectors do. See Script Configuration for details on script configuration.

Create a Connector Configuration

To enter values:

  • Enter the first three Connector fields manually. After validating the credentials in those fields, you can select values for the remaining fields from drop-down menus.
  • To enter values manually, click to put the cursor in the field and type the value, making sure that the case matches the value in Citrix Hypervisor.
  • To select a value from a drop-down list, do the following:
    • Click once to put the cursor in the field.
    • Click a second time to display the list of possible values.

To add a Connector Configuration

  1. Click the Connectors page.
  2. Click Add Connector Configuration. A dialog box opens.
  3. Select the Connector Type for the platform and location where you are creating the layer or publishing the image. Then, click New to open the Connector Configuration page.
  4. Type the configuration Name, and the Citrix Hypervisor Address, user name, and Password. For guidance, see the above field definitions.
  5. Click the CHECK CREDENTIALS button below the Citrix Hypervisor Configuration fields. The Virtual Machine Clone Settings field is then enabled.
  6. Select the Virtual Machine Template.
  7. Select the Storage Repository and click the TEST button to verify that the software can access the location specified using the supplied credentials.
  8. Click Save. The new Connector Configuration appears on the Connector page.

Script Configuration (Optional, Advanced feature)

When creating a Connector Configuration, you can configure an optional PowerShell script to run on any Windows machine running an Agent. Store the scripts on the same machine on which you install the Agent. The script runs only after a successful deployment of a layered image.

Some preset variables are available to enable scripts to be reusable with different template images and different connector configurations. The variables also contain information that identifies the virtual machine as part of the published layered image in Citrix Hypervisor.

Running the scripts does not affect the outcome of the publish job, and progress of commands that are run in the script are not visible. The Citrix Hypervisor connector logs contain the output of the script.

Configure a Script (optional)

  1. To run a script each time you publish a layered image, complete these steps by using the values described in the following sections.
  2. Complete and save the connector configuration as described above.


    Before selecting the Script Configuration page, save (or discard) any edits to the connector configuration settings,

  3. If the Navigation menu on the left is not open, select it and click Script Configuration to open the Script Configuration page.
  4. Complete the required fields using the values detailed in this topic and then click Save.

Script Configuration fields

  • Enable script - Select this check box to enable the remaining fields. You can enter a script that runs each time a layered image is published.
  • Script Agent - The agent machine where the scripts are located and run from.
  • User name (optional) - The user name to impersonate when running the script. The user name ensures that the script runs in the context of a user with the rights or permissions to perform the operations in the script.
  • Password (optional) - The password for the specified user name.
  • Script Path - A full path and file name on the agent machine where the script file resides.

Other Script Configuration values PowerShell variables When the script runs, the following variables are set and can be used in the PowerShell script:

Value Applies to connector types: Value determined by which code: Description
connectorCfgName All Common code The name of the connector configuration that the script configuration is associated with.
imageName All Common code The name of the layered image template that was used to build and publish the layered image.
osType All Common code The OS type of the published layered image. It can be one of the following values: Windows7; Windows764;Windows200864; Windows201264; Windows10; Windows1064
virtualInfrastructureServer All Citrix Hypervisor connector code The Citrix Hypervisor host specified in the connector configuration.
vmName All Citrix Hypervisor connector code The name of the virtual machine that was created.
vmId All Citrix Hypervisor connector code The virtual machine UUID (same as vmUuid)
vmUuid All Citrix Hypervisor connector code The virtual machine UUID (same as vmId)

Definition Scope Whether the scripts variable is set for all platform connector types or whether it is specific to a particular connector type.

Value Source Uses either common code or by platform connector-specific code to determine the variable value.

Citrix Hypervisor