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