Upgrade
Upgrading from release 2403 or earlier
If you are using a version of App Layering that is release 2403 or earlier, you must utilize the migration feature in order to access release 2409 or later. There is no in-place upgrade for release 2403 to release 2409. In order to upgrade, a new appliance running 2409 or later must be deployed, and then the migration feature must be used to migrate the configuration from the 2403 appliance to the newly deployed appliance. To access the migration feature, you will first need to confirm you are upgraded to the latest version of release 2403. The download for the latest version of release 2403 can be found here, or can be upgraded through the appliance.
You can refer to the Migrate Appliance documentation for additional details. At a high level, these are the steps requires to get your appliance running on release 2409 or later:
- Download and deploy the latest available release, configure your appliance, and run it on your network.
- Take a snapshot of BOTH your current 2403 appliance and the newly deployed appliances.
- Upgrade your 2403 appliance to the latest available version, which will include the migration feature.
- On the 2403 appliance, in the top-right user menu, click Migrate Appliance.
- There are two migration modes: Copy and Move:
- Copy will replicate the layer data and configuration to the new appliance, but not move or change any of the configuration in the old appliance.
- The new appliance will require manual configuration before initial use.
- Move will re-map the network file shares to the new appliance, and remove them from the old appliance.
- It will leave the old appliance without a configured network file share, and the new appliance will be ready for use.
- Copy will replicate the layer data and configuration to the new appliance, but not move or change any of the configuration in the old appliance.
- There are two phases to a migration, and user confirmation is required between Phase One and Phase Two in order to complete the migration process to the new appliance.
- A migration is a task, and can be monitored and managed via the task list in the UI.
Upgrading from release 2409 or later
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. The upgrade process is partially automated, in that the appliance periodically checks for the latest package. It downloads new packages, verifies, and extracts the files. Users receive a message the next time they log in, and administrators with proper permissions can start the upgrade.
Besides upgrading the App Layering appliance, also expect to upgrade the:
- App Layering agent, if it is installed on your hypervisor and provisioning servers.
- Published layered images (requires provisioning your servers with the images).
This article explains how to complete each of the associated upgrades.
Before you upgrade
- Verify that a network file share is configured.
- Back up the appliance.
Verify that a network file share is configured
You can confirm the share by logging on to the appliance and navigating to System > Network File Share. After ensuring you configured the file share, you can upgrade the appliance.
Back up the appliance
Take a snapshot or checkpoint of the appliance.
Upgrade the appliance
App Layering upgrades are partially automated. The appliance periodically checks for upgrades and downloads the latest one, as long as the correct permissions, and other requirements, are in place.
The Upgrade folder includes the appliance upgrade, the agent upgrade, and a folder of tools to use on your OS layer.
What happens if an upgrade is found
If an upgrade is found during the automated check, the latest available compressed folder is downloaded to your appliance. The appliance verifies the download, 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).
- Close: Dismisses the message, so you can manually start the upgrade later using User tab > Upgrade Appliance.
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.
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.
- Navigate to the .zip file and extract the files.
- Log on to the management console, select User and then click Upgrade Appliance.
- Verify the upgrade path, and click Upgrade. The upgrade process starts and opens a Statuspage in the browser.
- When the upgrade is complete, the status changes to Upgrade Status: Complete. Refresh the webpage to return to the management console.
- Verify that the upgrade was successful by clicking the About link in the management console to confirm the version number.
Upgrade the App Layering agent (if installed)
Next, upgrade the App Layering agent. This component enables an appliance or packaging machine to run PowerShell commands locally. You can expect to find the agent installed in the following locations, if they exist in your environment:
- Hyper-V servers that App Layering uses for layer creation or image publishing.
- Citrix Provisioning servers where you publish layered images.
- Servers where a connector configuration runs PowerShell scripts. To view any existing connector configurations, open the management console and select System > Connectors.
To upgrade the App Layering agent in those locations:
- Copy the agent upgrade file to the servers where the agent is installed.
- Double-click the agent upgrade file, and follow the instructions for upgrading the agent.
Upgrade 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:
- Log into the layering management console.
- Select the Images tab. Your image templates are displayed.
- 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.
- If the image template does not need editing, simply select the template, click Publish Layered Image.
- Once published, use the new layered images to provision your systems.
Background: 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.
Note:
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 “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.
Optional: How to check for available upgrades manually
Automated upgrade checks always pull the latest version, but you can manually check for updates.
To manually check for an update:
- Log into the management console.
- Click the User tab and then the Upgrade Appliance action. The latest version displays in the Upgrade Disk field.
If you are logged into a desktop as Administrator, and an Upgrade badge is displayed:
- Click Start Upgrade. The download information is displayed in the Upgrade Disk field.
- As Administrator, you can select a different Upgrade Disk.
Use the detailed steps in the earlier section, Upgrade the appliance.