The App Layering upgrade process is partially automated. The appliance periodically checks for upgrades, and downloads available packages to your appliance. The appliance verifies the downloaded package, and extracts the files in the background.

When you next log in, a message indicates that an upgrade is ready to install. As an administrator, you can choose to:

  • Start Upgrade: Run the App Layering appliance software upgrade.(Administrators only.)
  • Remind Me Later: Wait seven days before reopening the message. Applies to individual users’ desktops.
  • Close: Dismisses the message, so you can manually start the upgrade later using System tab > Manage Appliance > Upgrade.

Only an administrator can run the upgrade. Users who do not have administrator privileges cannot start the upgrade, but they can select Remind Me Later to postpone the next upgrade message for seven days.

Notification when an upgrade is available

When an upgrade is available, every user receives a notification when they log in.

Notifications you may receive include:

  • 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 and that the administrator needs to finish configuring a network file share before it can be downloaded and applied.
  • 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 is encountered that requires Administrator intervention (out of space on local storage, out of space on the network file share, invalid file found, etc.) the job fails with an appropriate error.


        If a job fails it will be retried at the next check interval regardless of whether the Administrator has resolved the fixed.

  • 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.

Before you start

  • Verify that a network file share has been configured. You can confirm the share by logging onto 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 for available upgrades (optional)

In most cases you won’t need to check for updates, given the periodic checks and notifications. However, if you want to check, you can. Here’s how.

  1. Log in as Administrator.

  2. Click the Start Upgrade button to open the Upgrade Wizard. The downloaded information is displayed in the Upgrade Disk field.


    As Administrator, you can select a different Upgrade Disk. You can also run the Upgrade “manually” by going to the System tab and selecting the Upgrade action as before. If an upgrade is available, the Upgrade Disk appears.

When a user who does not have administrator privileges logs in, the user cannot click the Start Upgrade button nor launch the Upgrade wizard. The user should report the available upgrade to their administrator.

Download and run the App Layering upgrade

If automatic downloading is not occurring due to firewall requirements, you can manually download the latest upgrade package from the Citrix download site. After downloading, copy the package to the network file share so that 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

As of Release 18.12, the appliance checks the privileges for the VMware vSphere connector configuration when you select the TEST or SAVE buttons. This guarantees that the appliance has the permissions to create, edit, and delete virtual machines. If you are upgrading from release 18.12 or earlier, it also means that you need to set a few more permissions to update your configuration. The permission must be assigned at the vCenter level, and you need to create a another role to do it.

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 this is the same account that has the Datacenter permissions set above.

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


    You can also set all permissions at the vCenter level if your security policy allows this, instead of splitting permissions like this.

Make sure the following permissions are enabled

Please ensure that the following permissions are enabled:

  • Datastore > AllocateSpace
  • Datastore > Browse
  • Datastore > FileManagement
  • Folder > Create
  • Global > CancelTask
  • Host > Config > SystemManagement
  • Network > Assign
  • Resource > AssignVMToPool
  • System > Anonymous
  • System > Read
  • System > View
  • VApp > Export
  • VApp > Import
  • VirtualMachine > Config > AddExistingDisk
  • VirtualMachine > Config > AddNewDisk
  • VirtualMachine > Config > AddRemoveDevice
  • VirtualMachine > Config > Annotation
  • VirtualMachine > Config > CPUCount
  • VirtualMachine > Config > EditDevice
  • VirtualMachine > Config > Memory
  • VirtualMachine > Config > RemoveDisk
  • VirtualMachine > Config > Rename
  • VirtualMachine > nfig > Resource
  • VirtualMachine > Config > Settings
  • VirtualMachine > Config > UpgradeVirtualHardware
  • VirtualMachine > Interact > ConsoleInteract
  • VirtualMachine > Interact > DeviceConnection
  • VirtualMachine > Interact > PowerOff
  • VirtualMachine > Interact > PowerOn
  • VirtualMachine > Interact > Reset
  • VirtualMachine > Interact > SetCDMedia
  • VirtualMachine > Interact > ToolsInstall
  • VirtualMachine > Inventory > Create
  • VirtualMachine > Inventory > CreateFromExisting
  • VirtualMachine > Inventory > Delete
  • VirtualMachine > Provisioning > Clone
  • VirtualMachine > Provisioning > CloneTemplate
  • VirtualMachine > State > CreateSnapshot

Settings that should NOT be enabled

For your reference, the following settings should not be enabled:

  • VApp > ApplicationConfig
  • VirtualMachine > Config > AdvancedConfig
  • VirtualMachine > Config > ChangeTracking
  • VirtualMachine > Config > ManagedBy
  • VirtualMachine > Config > ResetGuestInfo
  • VirtualMachine > Config > SwapPlacement
  • VirtualMachine > Interact > AnswerQuestion
  • VirtualMachine > Interact > ConsoleInteract
  • VirtualMachine > Interact > Suspend
  • VirtualMachine > Inventory > Register
  • VirtualMachine > Inventory > Unregister
  • VirtualMachine > Provisioning > Customize
  • VirtualMachine > Provisioning > DeployTemplate
  • VirtualMachine > Provisioning > MarkAsTemplate
  • VirtualMachine > State > RemoveSnapshot

Upgrade the App Layering agent (if you are using the agent)

To upgrade the App Layering agent:

  1. Make sure that you have copied the App Layering agent upgrade file to the server(s) where the agent is installed.
  2. Double-click the agent upgrade file, and follow the instructions for upgrading the agent.

Roll out the upgrade

App Layering upgrades include driver updates, along with the new features and bug fixes documented in the What’s new.

When you are ready to provision your systems with the upgrade, you need to select each of your image templates, verify the settings, and use it to publish new versions of your layered images. Once published, use the new layered images to provision your systems.

To roll out the upgrade:

  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 any settings you want to change, and on the last tab of the wizard, click Save Template and Publish.
  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.