App Layering

Connector configurations

The first time you use the App Layering service, plan to create one or more “connector configurations”. App Layering connector configurations are stored sets of credentials that the appliance uses to access locations on your hypervisor or provisioning server. A connector configuration can specify where to build a layer, or where to publish images.

Why use connector configurations

Connector configurations let the App Layering appliance access locations in your environment for creating layers or publishing layered images. Using a connector configuration automates the file transfer process and saves significant amounts of time.

You can use a connector configuration to:

  • Import an OS image into a new layer.
  • Create an app layer or platform layer, or add a version to an OS layer, and if you choose, also run a script.
  • Publish layered images to your hypervisor or provisioning server, and if you choose, also run a script.

Import your OS image into an OS layer

When you create an OS layer, you need a connector configuration to give the appliance access to the location of the OS image.

Create layers

Layer creation is easier when you use a connector configuration. The connector configuration includes the credentials for the location where you plan to install the software for a layer. This connector configuration includes a Packaging Cache option, which is enabled by default to afford you the best layering performance.

Publish layered images

You need a connector configuration for each location to which you are publishing layered images. Once published, you use layered images to provision systems for specific groups of users.


To create a connector configuration, you need to meet the following requirements.


Valid account credentials that the appliance can use to access a location in your environment. For details about the values you need, select the hypervisor or Provisioning Service later in this section.

About offloading layer compositing (Google Cloud, Hyper-V, and VMware vSphere only)

When creating a layer or publishing a layered image, you can use the built-in App Layering compositing engine to create layers. The compositing engine enables the Offload Compositing connector configuration option and the ImportOsLayer.ps1 script. You can use the script when creating an OS layer from scratch. Be sure to open the firewall ports required for the compositing engine


An OS layer is created (initially) by importing the OS from an existing virtual machine. Once created, you update the OS layer just like any other layer.

Offload compositing:

  • Increases performance.
  • Gives you the option of creating the layer or image as a UEFI or Generation 2 machine.
  • Uses VHDX disk format for either BIOS and Generation 1 machines, or UEFI and Generation 2 images.

To create a layer using Offload Compositing:

  • App layer, platform layer: Launch the Create Layer Wizard, and choose a connector configuration with Offload Compositing enabled.

  • OS layer: Run a script. For details, see Create OS layer.

Disk space for cache

On all supported hypervisors, except for Azure, the default Packaging cache size is set to the recommended starting level. Allow enough disk space to increase the cache size, if needed.

  • Creates the layer or image as a UEFI or Generation 2 machine.
  • Uses VHDX disk format for either BIOS and Generation 1 format, or UEFI and Generation 2 images.

To create and app or platform layer using Offload Compositing, you select a connector configuration with Offload Compositing enabled. To create an OS layer, you run a script instead. For details, see Create OS layer

Packaging layers

When using Offload Compositing in the connector configuration, packaging a layer begins when you shut down the machine for finalization. The packaging is done automatically. You do not have to manually select Finalize in the management console.


When creating an OS layer, do not use the Offload Compositing option in the connector configuration. You can run the script to create the layer. Another option is to build the OS on a BIOS or Generation 1 machine, then add a version to the layer with Offload Compositing selected.

When you select Offload Compositing, choose either UEFI or Generation 2 for the new layer version. Select VHDX for the disk format. VHDX format is supported on BIOS (Generation 1), and UEFI (Generation 2) machines.

Publish images

When you publish an image, the publishing machine builds the image on the hypervisor (Hyper-V, VMware vSphere) server.

About “Packaging cache size” and “Select rate”

Connector configurations for all hypervisors except Azure let you configure space for a Packaging cache. The appliance uses this cache on your hypervisor to speed up layer packaging.

Packaging cache size

We recommend using the default packaging cache starting size for your hypervisor:

  • vSphere: 250 GB
  • Citrix Hypervisor (formerly XenServer): 480 GB
  • Hyper-V: 200 GB
  • Nutanix: 480 GB

The more app layers you create, the larger the cache you need. Increase the Packaging cache size, if needed.

The Hit rate

The Hit rate is the percentage of times that the appliance has found a disk in the cache. A low value in this field indicates that the cache is not providing much value. Increase the cache size to accommodate more unique layers.

You can improve a low rate by increasing the Packaging cache size. Increasing the cache size allows more disks to be stored in the cache. It also increases the likelihood of finding a disk for packaging in the cache. The result is a higher hit rate value.

View connector configurations

The System > Connectors tab lists the connector configurations that you have created.

Image of the Connectors tab

Sort connector configurations

By default, connector configurations are listed in alphabetical order by name. You can also sort them by platform.

View connector configuration details

When caching is enabled for a connector configuration, the Connectors tab displays the cache size for that configuration.

Image of the cache size option

To see the values for any given connector configuration:

  1. Click the info icon to the left of the name. Details about the connector configuration are displayed.

View Cache size and Hit rate

The Packaging Cache Size and Hit rate are displayed when the Packaging Cache Size is set to a value greater than zero (0).

Add a connector configuration

This section explains how to add and manage a connector configuration on the System > Connectors tab.

A connector configuration speeds up the process of creating a layer or image template. If you need one to access a specific location, you can create one by selecting New on the wizard’s Connector tab. From there, use the detailed steps later in this section.

To add a connector configuration, follow these steps:

  1. Access the management console, and select System > Connectors to see your connector configurations, if you have created any.
  2. Click Add Connector Config in the Action bar. A dialog box opens where you can select the type of connector configuration to create.
  3. Choose the connector type from the drop-down menu.
  4. Complete the fields on the connector configuration page.
  5. Click the Test button to verify that the connector can access the location specified using the credentials supplied.
  6. Click Save. The new connector configuration appears on the Connector tab.

Image of the connector configuration

Edit a connector configuration

To edit a connector configuration:

  1. Access the management console, and select System > Connectors.
  2. Select the connector and click Edit Connector Config on the action panel. The connector configuration is displayed.
  3. Update the configuration, as needed.
  4. Click the Test button to verify that the connector can access the location specified using the credentials supplied.
  5. Click Save. The connector configuration is updated.

Increase the Cache size and Hit rate

To improve the utility of the cache and therefore increase the hit rate by editing the Packaging Cache Size:

  1. Select the connector and click Edit Connector Config on the action panel.
  2. Scroll to Layer Disk Cache Size in GB and enter the amount of space that the cache can occupy.
  3. Click the Test button to verify that the connector can access the location specified by using the credentials supplied.
  4. Click Save. The connector configuration is updated.

Continue adjusting the cache size until you achieve the layering performance you are looking for.

Disable or re-enable caching

Caching is enabled and set to a recommended starting size by default. We strongly recommend that you use caching.

If you disable caching for a connector configuration, set the cache size to zero (0). You can re-enable it by increasing the Packaging cache size.

Delete a connector configuration

To delete a connector configuration:

  1. In the management console, select System > Connectors.
  2. Make sure that the connector configuration is not in use.
  3. Click Delete Connector Config on the Action bar.
  4. In the pop-up window that opens, select Yes. The connector configuration is deleted.

The Connectors tab takes a few minutes to update after another administrator deletes a connector configuration.

Messages when deleting connector configurations

If a connector configuration is in use when you attempt to delete it, you receive a message similar to the following example.


Validation Error: Unable to delete connector configuration ‘Citrix Provisioning - ConnectorExample’ as it is in use. If you receive this error message, remove the connector configuration from the layer or image template where it is still in use. Then delete the configuration.