App Layering

MS Hyper-V

An MS-Hyper-V connector configuration includes the credentials and storage location the appliance needs to connect to Hyper-V, and it identifies the properties to be associated with the vDisk.

You can select a Hyper-V connector for importing the OS, creating other layers, or publishing layered images. Each connector configuration is set to access a storage location using a specific account.

The Hyper-V connector uses Microsoft’s Background Intelligent Transfer Service (BITS) to copy disks to and from the appliance. With BITS the appliance reports progress as a percentage complete, and the connector no longer requires a CIFS share.

The Hyper-V connector includes an Offload Compositing checkbox that enables layer packaging and image publishing to be done on the Hyper-V server, rather than on the App Layering appliance. Offload Compositing greatly increases the speed of layer packaging and image publishing. It also automates layer finalization and lets you create layers and publish images as Hyper-V Generation 2 machines on VHD or VHDX disks.

For more about connectors and connector configurations in general, see Connector configurations.

Before you start

The first time you create an image template for publishing layered images to your Microsoft Hyper-V environment, you need to add a new Hyper-V connector configuration for that location.

Hyper-V requirements

You can use a Hyper-V connector configuration makes it easy to connect to a location in your Microsoft Hyper-V environment.

The information you need for the Hyper-V connector configuration includes:

  • Hyper-V Configuration
    • Agent - App Layering agent from the list of agents registered with the appliance. The agent runs under the machine account for the machine it is running on.
  • Virtual Machine Settings
    • Template VM (Optional) - A template that can be used to clone a Hyper-V virtual machine with the desired hardware settings (memory, CPUs and video settings). You can specify the host, data store and network for configuring the resulting virtual machines. The template must have at least one network card attached, and it must not have any disks attached. Otherwise, you receive an error when attempting to validate or save the configuration.
    • Number of CPUs - Number of CPUs to use for creating a Packaging Machine or publishing a layered image. The default value is 4 CPUs.
    • Memory (Mbs) - Amount of memory allocated for creating the Packaging Machine or the layered image Machine. The default value is 8192 Mb.
    • Network - Network switch. You can select from a list of network switches known by the agent.
    • Generation - Generation 1 machines are supported in all cases. Generation 2 machines are supported only when the Offload Compositing option is selected.
    • Disk Format - VHD or VHDX are supported on Generation 1 machines. Only VHDX is supported on Generation 2 machines.


      VHDX disk format requires Offload Compositing, even on Generation 1 machines.

    • Offload Compositing - Enables the layer packaging or image publishing process to run on the specified Hyper-V server. This feature increases performance, and it allows you to use VHDX disk format and Generation 2 VMs. 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.)
  • Storage Settings
    • Path to Storage, eg: C:\Virtual Machines - Path for the local or remote location where the App Layering software creates layer disks, packaging machines, and layered image disks. This value:
      • Must be the same as the location specified in the UNC path.
      • Cannot be a mapped drive.
    • Layer Disk Cache Size in GB (optional) - Amount of File Share space (in gigabytes) to use for caching layer disks. A value of:
      • 0 disables layer caching.
      • 1+ enables layer caching and specifies the amount of space to allow for caching layer disks on the File Share. Copies of boot disks and packaging disks are stored and then reused wherever possible to reduce the time it takes to package an app layer.

App Layering requirements

The App Layering agent is required to use a Hyper-V connector. The App Layering agent must be:

Create a Hyper-V connector configuration

To use the Hyper-V connector for layering or publishing, you:

  1. Click the Connectors page.
  2. Click Add Connector Configuration. This opens a small dialog box.
  3. Select the Microsoft Hyper-V Connector Type. Then click New to open the Connector Configuration page.
  4. Complete the fields on the Connector Configuration page. For guidance, see the field definitions in the Hyper-V requirements section above.
  5. Click the TEST button to verify that the appliance can access the location specified using the credentials supplied.
  6. Click SAVE. The new connector configuration should now be listed on the Connector tab.

HTTPS and certificate errors

By default, HTTPS is turned off and certificate errors are ignored, because the self-signed certificate that comes with the appliance would fail over HTTPS. When you upload your own certificate, you can configure the connector to use HTTPS and to stop ignoring certificate errors.

If you want to enable HTTPS for Hyper-V

if you want to enable HTTPS for Hyper-V, edit the settings for turning on HTTPS and for ignoring certificate errors in the config.json file.

  1. Open the Hyper-V connector config.json file:


  2. Set useHttpsFileTransfer to true:

    “useHttpsFileTransfer”: true

  3. Set ignoreCertificateErrors to false:

    “ignoreCertificateErrors”: false

  4. Restart the Hyper-V connector.

Certificate errors

Once certificate errors are no longer ignored, you will receive the following error if your certificate expires:

Failed copying file to D:\path\file.vhdx. The certificate authority is invalid or incorrect.
The error occurred while the remote file was being processed.
MS Hyper-V