Appliance Operating System Migration Support

Appliances deployed before June 27th, 2024 are based on an older underlying OS that will stop receiving application and OS security updates on June 30th, 2025.

We have developed a simple way for customers to update to the newer OS without needing to redeploy. The process itself and the steps required to complete this migration are documented here.

Only older appliances will show a notice on the dashboard alerting of the pending upgrade. If there are doubts, the Collect Troubleshooting Info function on the Interfaces page can be used to check the appliance's build date.

This topic is organized into the following sections:

Quick Steps to Upgrade to a Newer Appliance OS
Upgrade Prerequisites and Overview of Processing at Each Stage
Detailed Overview of the Upgrade Steps
Troubleshooting

Quick Steps to Upgrade to a Newer Appliance OS

This section describes the quick steps needed to upgrade to a new appliance OS without needed to redeploy. For additional reference information on these steps, see Upgrade Prerequisites and Overview of Processing at Each Stage as well as Detailed Overview of the Upgrade Steps.

To update to a newer appliance OS without needing to redeploy:

1. Take a VM-level snapshot (backup) of the appliance. This will allow easily rolling things back if an issue occurs during the upgrade.
2. Download the components required for the upgrade by clicking the Download Components button. The following components will be downloaded:
Upgraded versions of all OS packages. This includes the OS kernel and userland, database, and web services.
Scripts required to run the upgrade.
Updated OS config files.
3. Begin the actual upgrade by clicking the Begin Migration button.

Upgrade Prerequisites and Overview of Processing at Each Stage

The following table provides a list of upgrade prerequisites and provides processing details that occur at each stage of the upgrade.

Overview of the Upgrade to a Newer Appliance OS Process

Component

Description

Prerequisites

Sufficient free disk space is available
All pending OS security and application updates are installed
No unexpected software is installed
No unexpected local configuration changes have been made
No recent database errors are seen in logs
System files pass integrity check
Appliance is not running (RN150) or aggregating (FlexDeploy) a discovery scan

Stage 1

Scheduled tasks (for example, performance collection) are paused
Any in-progress performance collection (RN150) or aggregation (FlexDeploy) is stopped
A temporary hold is placed on any changes to the Flexera application packages
Make a few necessary (temporary) config adjustments to ensure subsequent package upgrades run smoothly
Upgrade OS packages
Install new packages, such as an updated firewall service and Java runtime
Purge obsolete packages, such as older versions of Python and PHP
Install new/updated OS config files and remove obsolete ones
FlexDeploy-only—Update local API service to be compatible with newer Java runtime

Stage 2

Upgrade database server to an intermediate version

Stage 3

Upgrade database server to final version
Purge any remaining obsolete or unused packages
Remove any backup copies of stock config files
Scheduled tasks are resumed
The temporary hold is removed from Flexera packages
Postinstall actions for Flexera packages are executed again, to ensure any specific to the new OS have run
Performance collection (RN150) or aggregation (FlexDeploy) is started
Appliance is automatically rebooted into the updated OS

Detailed Overview of the Upgrade Steps

A detailed overview of the upgrade steps is included for reference.

Steps to upgrade

1. From the appliance configuration interface, click the click here link in the update notice at the top of the page. Alternatively, you can directly navigate to /migrate.php by editing the URL in the browser.

Note:On FlexDeploy, the configuration interface runs on port 8443 . For example:
https://flexdeploy.example.org:8443

2. You are taken to a page containing a few key elements: Download Components, Begin Migration, Migration Log, and Full Output. From here, click the Download Components button and wait for it to complete. The Status field will say Migration components have been downloaded when complete. At this point, the Begin Migration button becomes clickable.
3. After ensuring that a recent VM snapshot has been taken and that no discovery is in progress, click the Begin Migration button. It is recommended to run this from a PC rather than the VMware console as it will allow downloading logs afterwards. Do not reboot the appliance while this is running. Any attempt to navigate back to the Dashboard will automatically redirect you to the Migration page at this time.
4. You will start to see output in both the Migration Log and Full Output fields. The Migration Log field contains messages describing the progress of the upgrade, and the Full Output field shows the output of the underlying commands run during the upgrade. If the Migration Log seems to pause while the upgrade is running, the Full Output will show that things are still moving along behind the scenes.
5. At the end of the upgrade which will take approximately 30 minutes depending on the speed of the hardware and size of the underlying database, the appliance will automatically reboot. The status will change to Rebooting.... When this is completed, the status changes to Migration completed and a link appears at the top of the page returning you to the Dashboard.
6. The look, feel, and functionality of the appliance will be identical after upgrading, with one key difference: the appliance version shown in Collect Troubleshooting Info shows a +bookworm suffix in the version name. At this point, performance collection (RN150) and aggregation (FlexDeploy) will automatically resume and the appliance can be used normally.

Troubleshooting

The following table provides migration troubleshooting help.

Troubleshooting Appliance Operating System Migration

Point of Failure

 

If the Download Components step fails

The status will change to Previous attempt to download migration components failed. Please try again or contact support if the issue persists. As the message states, try again, and open a support case if this persists.
A couple possible causes here could be network issues or a lack of available disk space on the appliance.

If the Begin Migration step fails

The status will change to Migration interrupted; please check logs and try again, or contact support if this persists. It is recommended to download both the Migration Log and Full Output at this point before starting the process again. The Migration Log field should show the reason for this; if it's not clear, detailed output will appear in the Full Output section. If the migration fails repeatedly, please reach out to support.
If the process fails quickly, it's possible that the prerequisite checks (described earlier in Upgrade Prerequisites and Overview of Processing at Each Stage) failed. No changes will have been made yet to the appliance in this case.
If the appliance was power cycled during the upgrade, the process automatically restarts on boot. However, if the process was interrupted at a critical section, the appliance could be rendered unbootable. Restoring to the recent VM snapshot would be advisable in this case, and then to start the process again.