For the latest fixes and features, including compatibility with other software packages that you use, we encourage you to stay current with the App Layering upgrades.

To upgrade the App Layering software, you:

  • Upgrade the App Layering appliance
  • Upgrade the App Layering agent on each of the hypervisors and provisioning servers where it is installed
  • Upgrade the layered images you have published, and reprovision your servers using the new images.

This article explains how to run each of these upgrades.

Before you upgrade

Before starting the upgrade:

  • Verify that a network file share is configured.
  • Back up the appliance.
  • Check the supported upgrade path (for pre-19.1 versions only)
  • (Optional) Manually check for an upgrade.

Verify that a network file share is configured

You can confirm the share by logging on to the appliance, navigating to System > Settings and Configuration, and finding the network file share setting. After ensuring you configured the file share, you can upgrade the appliance.

Back up the appliance

Take a snapshot or checkpoint of the appliance.

Check the supported upgrade path (For pre-19.1 versions only)

If you are upgrading from an older version of the product, use the following upgrade path to bring your installed version up-to-date.

Upgrade from Version To Version
4.1 4.15
4.15 19.1
19.1 or later Current version

Although older upgrades are not publicly available on our download page, any Support engineer (Front Line or Escalation) can supply a link to any App Layering version.

To get the link for a specific upgrade, open a Support case.

(Optional) Manually check for available upgrades

Automated upgrade checks always pull the latest version, but you can manually check for updates.

To manually check for an update:

  1. Log into the management console.
  2. Click the System tab and then the Upgrade action. The Upgrade Wizard opens, and displays the latest version in the Upgrade Disk field.

If you are logged into a desktop as Administrator, and an Upgrade notification is displayed:

  1. Click the Start Upgrade button to open the Upgrade Wizard. The download information is displayed in the Upgrade Disk field.
  2. As Administrator, you can select a different Upgrade Disk.

Use the detailed steps in the next section to continue with the upgrade.

Upgrade the appliance

The App Layering upgrade process is partially automated. The appliance periodically checks for upgrades. The appliance downloads the latest upgrade as long as the correct resources are in place.

What happens if an upgrade is found

If an upgrade is found during the automated check, the latest available package is downloaded to your appliance. The appliance verifies the downloaded package, and extracts the files in the background.

Meanwhile, every user receives one of the following messages the next time they log in:

  • Start Upgrade: Run the App Layering appliance software upgrade. (Administrators only).
  • Remind Me Later: Wait seven days before reopening the message. For end users (non-administrators), this option prevents the message from appearing when they log on to their desktops.
  • Close: Dismisses the message, so you can manually start the upgrade later using System tab > Manage Appliance > Upgrade.

For more detail about what the appliance checks for, see How the upgrade checks work, in detail.

Who can start the upgrade

Only an administrator can start the upgrade. The Remind Me Later option lets other users shut off the upgrade message for seven days.

If your firewall prevents automatic downloads of the upgrade package

If firewall requirements prevent automatic downloading, download the upgrade package from the Citrix download site. Copy the package to the network fileshare where the appliance can access it.

  1. Navigate to the .zip file and extract the files.
  2. Log on to the management console, select System and then click Upgrade to start the Upgrade Wizard.
  3. On the Upgrade Disk Details tab, click Browse.
  4. Navigate to the upgrade file, and click Choose.
  5. Verify the upgrade path, and click Upgrade. The upgrade process starts and opens a status page in the browser.
  6. When the upgrade is complete, the status changes to Upgrade Status: Complete. Refresh the webpage to return to the management console.
  7. Verify that the upgrade was successful by clicking the About link in the management console to confirm the version number.

If you are upgrading from App Layering 18.12 or earlier (VMware vSphere only)

As of Release 18.12, the TEST and SAVE buttons check the VMware vSphere privileges. A pass means that the appliance has permissions to create, edit, and delete virtual machines.

If upgrading from release 18.12 or earlier, expect to set a few more permissions that are now required. Create another role and assign the permissions at the vCenter level.

Create another role

Because the Virtual Machine > Inventory > Remove permission must be assigned at the vCenter level, you must create another role.

  1. In the vSphere Client, navigate to Home > Administration > Roles.
  2. Click Add Role, and enter a name, for example: CALAdmin-vmremove.
  3. Add only Virtual Machine > Inventory > Remove. Everything else can remain read-only.
  4. In the vSphere Client, navigate to Home > Inventory > Hosts and Clusters.
  5. Select the vCenter Permissions tab, right-click, and select Add permission (or modify the permissions on an existing account).


    Make sure the account is the one that owns the data center permissions set previously.

  6. Select the new CALAdmin-vmremove role you defined. Make sure the Propagate to Child Objects check box is selected and then click OK.


    You can set all permissions at the vCenter level, if your security policy allows it.

Enable vCenter permissions

Enable the permissions listed in the Install appliance in vSphere article.

Disable the following settings

For your reference, be sure to disable the following settings:

  • vApp
    • Application Configuration
  • Virtual Machine
    • Configuration
      • Advanced Configuration
      • Change Tracking
      • Managed By
      • Reset Guest Info
      • Swap Placement
    • Interact
      • Answer Question
      • Console Interact
      • Suspend
    • Inventory
      • Register
      • Unregister
    • Provisioning
      • Customize
      • Deploy Template
      • Mark As Template
    • State
      • Remove Snapshot

Once the appliance is upgraded

After the App Layering appliance runs the upgrade, upgrade the App Layering agent installed on your servers, and apply the upgrade to your published layered images.

Upgrade the App Layering agent (if installed)

The agent is installed on the following hypervisor and provisioning servers:

  • On all Hyper-V servers you plan to use for layer creation or image publishing.
  • On any Citrix Provisioning servers where you plan to publish layered images.
  • In locations where your connector configurations run PowerShell scripts.

To upgrade the App Layering agent in those locations:

  1. Copy the agent upgrade file to the servers where the agent is installed.
  2. Double-click the agent upgrade file, and follow the instructions for upgrading the agent.

Apply the upgrade to your published layered images

App Layering upgrades include driver updates, new features, and the bug fixes documented in the What’s new. Once you upgrade the appliance, upgrade your published images.

To upgrade your published images, you select each of your image templates, verify the settings, and use it to publish new versions of the layered images. Use the new images to provision your systems.

To apply the upgrade to your published layered images:

  1. Log into the layering management console.
  2. Select the Images tab. Your image templates are displayed.
  3. If you want to verify or update a template’s settings, select the image template, and click Edit Template. Edit the settings and click Save Template and Publish on the last tab of the wizard.
  4. If the image template does not need editing, simply select the template, click Publish Layered Image on the action bar. In the wizard that opens, click Publish Layered Image.
  5. Once published, use the new layered images to provision your systems.

Reference: How the upgrade checks work, in detail

When the App Layering appliance checks for an upgrade:

  • If an update is not available: Nothing happens. Another check is made at the next scheduled interval.
  • If an update is available, but there is no network file share configured: The user receives a message that there is an upgrade available. It asks you to finish configuring the network file share.
  • If an update is available: A job is started to “Download Upgrade Media.” You can check for progress through the following tasks:
    • Downloading the upgrade media to local storage.
    • Ensuring the checksum of the successfully downloaded upgrade package is correct.
    • Extracting the downloaded upgrade package to the configured Network File Share. The download is extracted to the appliance’s file share: Location: NetworkFileShare*AppLayeringVersion* Example: \MyServer\AppLayeringFileShare\4.0.8
      • If extraction is successful, the next time any user logs in they will be notified that an upgrade is available.
      • If at any time during this process an error requires Administrator intervention, the job fails with an error. For example:
        • Out of space on local storage.
        • Out of space on the network file share.
        • Invalid files found.


        If a job fails, it retries at the next check interval, regardless of whether the issue has been resolved.

  • If another update is found before a previously downloaded one is installed - The new upgrade is downloaded, and once successfully completed, becomes the “Upgrade Available.”
  • If one upgrade is downloading when another is made available - The running download is aborted and a new download is started. All files related to the in-progress download are deleted.