App Layering

Machine creation for Citrix Hypervisor

The Machine Creation for Citrix Hypervisor Connector Configuration contains the information that allows the Citrix App Layering appliance to publish layered images to Machine Creation in your Citrix Hypervisor environment. The information includes user credentials and storage location.

To publish layered images, use the machine creation for Citrix Hypervisor Connector Configuration. In the Connector Configuration, ensure that you configure a virtual machine template. Then, the layered image you publish is in a ready-to-use virtual machine, the image is shut down and a snapshot taken. You can use the virtual machine in your Citrix Hypervisor environment without further modifications.

Each Connector Configuration is set to publish layered images to a specific storage location in your environment. If you publish to multiple locations, you might need more than one machine creation Connector Configuration. You can also publish each layered image to a location convenient to the system you provision with the published image.


This Connector Configuration is for publishing layered images. You cannot package layers in the machine creation environment. For packaging layers, use a Citrix Hypervisor Connector Configuration.

A Personal vDisk is not supported for machine creation. The published desktop images are non-persistent. You can only use a Personal vDisk when you publish to Citrix Provisioning.

Before you start

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 might 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 where you provision the published image.

Citrix Hypervisor uses a pod-like architecture where you interact with individual servers or clusters of servers, instead of a central management server. You manage the pods by using command-line access or GUI management software such as XenCenter. Install XenCenter on your desktop and then you can connect individually to each standalone host or to clusters of hosts.

Using the App Layering Service for the first time

If you want to create 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 need a Connector Configuration for each of your publishing locations as well.

You select a Connector Configuration when creating an app layer and publishing a layered image. If you need a Connector Configuration for the task, you can create one. To do so, click Add Connector Configuration on the Connectors page.

Required information for Machine creation for Citrix Hypervisor connector configuration settings

When configuring a connector for Machine Creation for Citrix Hypervisor, you can browse for the XenCenter server, data store, and host to use for a new configuration.


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

  • Configuration name - The name for the 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 Protocol - The default setting that allows SSL encryption for the API connection traffic between the Connector and Citrix Hypervisor.
  • Allow Certificate Errors - Enables the system to ignore certificate errors. By default, this setting is disabled.
  • Virtual Machine Template - The virtual machine template that you can use for cloning. The list of choices includes custom virtual machine templates only, rather than actual virtual machines or any of the built-in templates. The selected template cannot have any disks attached and must have at least one network card attached. If the template does not have these items, an error appears when trying to validate or save the configuration.
  • Storage Repository - The storage repository for the uploaded disk. The list is filtered to show repositories that can contain virtual hard disks (VHDs). ISO repositories are filtered out.
  • Use HTTPS for File Transfers - Encrypts the image file transfers. HTTPS is selected by default for uploads and downloads. You can clear the check box for increased performance.

Virtual Machine Organization

You can organize Citrix Hypervisor virtual machines by folder or by tag. These organizational tools are optional when creating and managing virtual machines through XenCenter or other tools. Citrix Hypervisor Connector Configurations do not allow you to specify folders or tags. Virtual machines created by the Citrix Hypervisor Connector, both Packaging Machines, and published Layered Image can use both organizational tools.


If the template specified in the Citrix Hypervisor connector configuration contains tags, the tags carry over to any virtual machine cloned from that template. Therefore, all packaging virtual machines or published layered images receive the same tags that are in the template. Additionally, the Citrix Hypervisor Connector adds three tags.

  • Unidesk - Lists all virtual machines created by the Citrix Hypervisor Connector regardless of their purpose or image.
  • Purpose Tag - Tags all packaging machines with App Layering Packaging Machine. Tags all published layered image virtual machines with App Layering Published Images.
  • Image/Layer Name - Provides a tag on all packaging machines with the layer name for the layer from which they generate. Tags all published layered images with the template image name.

If you are using XenCenter, you can view your virtual machines by tag by selecting Organization Views and then selecting By Tag.


By default, virtual machines created by the Citrix Hypervisor Connector are not placed in a folder. If the specified template is in a folder, the virtual machines that the Connector Configuration creates are in the same folder. All packaging virtual machines and published layered images are placed in that same folder. There are not separate folders for packaging virtual machines or published layered images.

Machine Network Connectivity

When you create virtual machines with the Citrix Hypervisor Connector, the virtual network settings in the source template of the Connector Configuration carries over. An option is not available in the Connector Configuration UI to override the network settings.

The Citrix Hypervisor connector does not work correctly with Citrix Hypervisor clusters. If the host in the configuration is part of a cluster, you must specify the primary host for the connector to work. However, if the primary Citrix Hypervisor host fails and a new primary is elected, you must update the Citrix Hypervisor configuration.

Create a Connector Configuration

To type values:

  • Type 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 type 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, click once to put the cursor in the field. Then, 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.
  4. Click New to open the Connector Configuration page.
  5. Type the configuration Name, the Citrix Hypervisor Address, User Name, and Password. For guidance, see the previously described field definitions.
  6. Click CHECK CREDENTIALS under the Citrix Hypervisor Configuration field, which enables the Virtual Machine Clone Settings field.
  7. Select the Virtual Machine Template.
  8. Select the Storage Repository and click TEST to verify that App Layering can access the location specified by using the supplied credentials.
  9. Click Save. The new Connector Configuration appears on the Connector page.

Script configuration (optional, advanced feature)

When you create a Connector Configuration, you can configure an optional PowerShell script to run on any Windows machine running an App Layering 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 contain the information to identify the virtual machine that is part of the published layered image in Citrix Hypervisor.

Running these scripts do not affect the outcome of the publish job, and the progress of commands run in the script are not visible. The Citrix Hypervisor connector logs contain the output of the script after it runs.

Configure a script (optional)

  1. Complete and save the Connector Configuration as previously described.


    Before selecting the Script Configuration page, you must save (or discard) any edits to the Connector Configuration settings,

  2. In the left Navigation menu, click Script Configuration to open the Script Path page.

  3. Complete the required fields by using the values in the table in the section Other Script Configuration Values and then click Save.

Script Configuration fields

  • Enable script - Select this check box to enable the remaining fields. After enabling the script, you can choose the script that runs each time you publish a layered image.
  • 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 name ensures the script runs with the required user rights and 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

When you run the script, it sets the following variables, which you can use 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 is associated with the script configuration.
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 operating system 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

When the script variable is set for all platform connector types, or when it is specific to a particular connector type.

Value Source

Determines if the variable value is common code or by connector-specific code.

Machine creation for Citrix Hypervisor