App Layering

VMware vSphere

A vSphere connector configuration contains the credentials and storage location that the appliance needs to connect to vSphere. Use the vSphere connector to package layers and publish images to VMware vSphere or VMware Cloud on AWS.

Before you start

You can use your vSphere environment to create layers, and to publish layered images. Each connector configuration accesses a specific storage location.

For convenient system provisioning, you can publish layered images to more than one location in your hypervisor. To publish to more than one location, create a connector configuration for each location. For more about connectors, and connector configurations, see Connect.

The vCenter account that you use for the connector must have the same permissions on a data center as are listed in the App Layering appliance installation article.

When using vSphere as the hypervisor for Citrix Provisioning, we recommend using the same vSphere VM template, in the vSphere connector settings, for creating layers as you do for creating the Target Devices in Citrix Provisioning. This practice ensures the published image and the target devices have the same baseline VM specs.

If this is your first time using App Layering

If this is your first time using App Layering and you want to create layers using a vSphere virtual machine, you need a vSphere connector. If you are also publishing layered images to vSphere, you can create a connector configuration for each of your publishing locations also.

The Create Layer and Publish Layered Image wizards each ask 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 New on the Connector wizard tab, or by proceeding to System > Connectors > Add Connector Configuration in App Layering.

Virtual controllers

You can use either the default LSI Logic SAS controller, or a VMware paravirtual SCSI controller.

Note: You cannot publish Windows 7 UEFI images, because Windows 7 is not compatible with UEFI.

To use the default LSI Logic SAS controller, simply select it for the layer’s virtual machine, and make sure that all of your layers use the same controller.

To use a VMware paravirtual SCSI controller, you need a pre-existing Template VM with a VMware Paravirtual SCSI controller and without any disks.

To use an existing LSI OS Layer with a VMware Paravirtual SCSI controller

If you have an OS layer with an LSI Logic SAS controller, and you want to use it with a VMware Paravirtual SCSI controller you can use either of the following approaches:

  • Add a version to the OS layer, using a VMware vSphere connector with an LSI Logic SAS VM template. When the packaging machine is created, follow the steps below to make the OS layer Paravirtual enabled.

  • Add a new platform layer with an LSI OS layer, and a platform connector with an LSI Logic SAS VM template. When the packaging machine is created, follow the steps below to make the platform layer Paravirtual enabled.

When the packaging machine from your chosen approach is ready:

  1. Log into the virtual machine and shut it down.
  2. In the vSphere Web Client open the Edit Settings page for the packaging machine.
  3. Add a new SCSI controller, by selecting SCSI Controller from the New Device menu, and click Add.
  4. Expand the New SCSI controller section that was added, and set Change Type to VMware Paravirtual.
  5. Add a new hard disk, by selecting New Hard Disk from the New device menu, and clicking Add.
  6. Expand the New Hard disk section and set the following parameters:
    • Size: 1 GB
    • Disk Provisioning: Thin provision
    • Virtual Device Node: New SCSI controller default bus
  7. Click OK.
  8. Install the Paravirtual drivers by powering on the packaging machine, logging in, and then shutting down.
  9. In the vSphere Web Client, open the Edit Settings page for the packaging machine.
  10. Remove both the hard disk and the Paravirtual controller that you added earlier in this procedure.
  11. Power on the packaging machine, log in, and click Shut down For Finalize.

Once you finish creating the layer, you can use it to create an image with a Paravirtual controller.

Required information for vSphere connector configuration settings

The vSphere connector configuration wizard lets you browse for the vCenter Server, Data Store, and Host to use for a new configuration.


The fields are case sensitive, so any values that you enter manually must match the case of the object in vSphere, or the validation fails.

  • Connector Configuration Name- A useful name to help identify and keep track of this connector configuration.
  • vCenter Server- The name of the vSphere server with which the appliance integrates.
  • vCenter User Name- The user name of the account that the appliance uses to connect to vSphere.
  • vCenter Password- The password of the account that the appliance uses to connect to vSphere.
  • DataCenter Name- The name of the vSphere data center in which the App Layering appliance creates and retrieves virtual machines.
  • Packaging Cache Size in GB (recommended)- The size of the Disk Cache that App Layering uses when creating layers. If you leave the size blank or set it to 0, App Layering does not use a Disk Cache. If you specify a size, App Layering users a Disk Cache of up to this size to keep copies of boot disks and packaging disks and reuses these disks to create new packaging machines. The reuse of these boot disks and packaging disks reduces the time it takes to package an App layer.
  • Virtual Machine Template - (Optional.) Virtual Machine Template that clones a virtual machine with the hardware settings for VMware, including memory, CPUs and video settings. This setting lets you specify the host, datastore and network for configuring the resulting virtual machines. You must use a template virtual machine (VM) for the virtual machine’s network to work correctly in VMware Cloud. When selecting a template virtual machine:
    • Answer Yes to the prompt asking to update settings, but do not change the network.
    • Make sure that the OS version used by the selected template matches the OS version that you are using for building layers or publishing layered images.
    • The template must not have any disks attached, and must have at least one network card attached. Otherwise, you receive an error when trying to validate or save the configuration.
  • ESXHost Name- The name of thevSphereESX Host on which the appliance will create and retrieve virtual machines.
  • DataStore Name- The name of the vSphere DataStore in which the appliance will create and retrieve virtual machines.
  • Network Name- The name of the vSphere Network in which the appliance will create and retrieve virtual machines.
  • Virtual Machine Folder Name- The name of the vSphere Folder in which the appliance will create and retrieve virtual machines.
  • Offload Compositing - Enables the layer packaging or image publishing process to run on the specified vSphere server. This feature increases performance, and it allows you to use VMDK disk format and either BIOS or UEFI virtual machines. With UEFI, you can also use Secure Boot if it is enabled on the VM.

    When Offload Compositing is selected:

    • If you do not provide a virtual machine template, the virtual machine defaults to BIOS.
    • If you provide a template configured for BIOS or UEFI, the resulting virtual machine is the type you chose.
    • If you provide a template with UEFI-Secure Boot enabled and selected, the resulting VM is UEFI-Secure Boot.

    When Offload Compositing is not selected:

    • If you do not provide a template, the virtual machine defaults to BIOS.
    • If you provide a template configured for BIOS, the resulting virtual machine is BIOS.
    • If you provide a template configured for UEFI, the machine fails to boot, and results in a blue screen. (Offload Compositing is required for UEFI.)

Required Privileges for the connector’s vSphere Client Administrator Role

Set the VMware privileges required by the vSphere Client Administrator to match the permissions for the App Layering appliance.

Once you have set the permissions, verify them by clicking TEST in the Connector wizard.

Create a connector configuration

To enter values:

  • The first three vCenter fields must be entered manually. Once the credentials in those fields are validated, you can select values for the remaining fields from the 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 vCenter.
  • To select a value from a drop-down list, click once to put the cursor in the field, and a second time to display the list of possible values.

To add a new connector configuration

  1. On the wizard for creating a layer or for adding a layer version, click the Connector tab.
  2. Below the list of connector configurations, click the New button. This opens a small dialog box.
  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. Enter the configuration Name, and the vCenter Server, vCenter User Name, and vCenter Password. For guidance, see the above field definitions.
  5. Click the CHECK CREDENTIALS button below the vCenter fields. The data center field is then enabled with a list of data centers available.
  6. Select the data center, enabling the remaining drop-down lists.
  7. Complete the remaining fields and click the TEST button to verify that App Layering can access the location specified using the credentials supplied.
  8. Click Save. Verify that the new connector configuration is listed on the Connector page.

Script Configuration (Optional, Advanced feature)

When creating a connector configuration, you can configure an optional PowerShell script on any Windows machine running an App Layering agent, the same agent used on the Citrix Provisioning server. The scripts must be stored on the machine where the App Layering agent is installed, and will only run 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. These variables also contain information needed to identify the virtual machine created as part of the published layered image in vSphere.

Running the scripts does affect the outcome of the publish job, and the progress of the script is not visible. The vSphere connector logs contain the output of the script after it runs.

Configure a Script

Remember that this is an optional procedure. If you want a script to run each time a layered image is published, complete these steps using the values described in the sections that follow.

  1. Complete and save the connector configuration as described above.


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

  2. If the Navigation menu on the left is not open, select it and then click Script Configuration to open the Script Path page.

  3. Complete the required fields using the values detailed herein, and click Save.

Script Configuration fields

  • Enable script- Select this check box to enable the remaining fields. This allows you to enter a script that will be run each time a layered image is published.
  • Script Agent- The agent machine where the scripts will be located and run from.
  • Username (optional)- The user name to impersonate when running the script. This can be used to ensure the script runs in the context of a user that has the permissions to perform the operations in the script.
  • Password (optional)- The password for the specified user name.
  • Path- A full path and file name on the agent machine where the script file resides.

Other Script Configuration values

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 This is the name of the connector configuration with which the script configuration is associated.
imageName All Common code This is the name of the layered image template that was used to build/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; Windows8; Windows864; Windows200864; Windows201264; Windows10; Windows1064
virtualInfrastructureServer All vSphere connector code The vCenter server specified in the connector configuration.
vmName All vSphere connector code The name of the virtual machine.
vmId All vSphere connector code The virtual machine ID from the VM (that is, “vm-12345”).
vmUuid All vSphere connector code The virtual machine UUID.

User Impersonation

The App Layering agent, which runs as a service on a Windows machine, runs under either the local system account or the network account. Either of these accounts may have some special privileges, but they often are restricted when running specific commands, or seeing files in the file system. Therefore, App Layering gives you the option of adding a domain user and password that can be used to “impersonate” a user. The script can be run as if that user had logged on to the system so that any commands or data are accessible with those user rights and permissions. If no user name or password is entered, the script runs using the account under which the service is configured to run.

Script Execution Policy

Script execution policy requirements are up to you. If you intend to run unsigned scripts, you must configure the execution policy to one of the more lenient policies. However, if you sign your own scripts, you can choose to use a more restrictive execution policy.

Error messages

If you receive ENOTFOUND errors when deploying a packaging machine or publishing an image, use the IP Address in place of the FQDN for the vCenter server.

VMware vSphere