Managing CentOS Migrations and RHEL Upgrades

Before beginning an upgrade, make sure that your systems are prepared according to your upgrade plan. This preparation might include backing up user and application data, taking a full system backup, or taking a snapshot of the system. Preparing your systems should also include running a pre-upgrade analysis and fixing potential issues.

After preparing your systems to upgrade, you can use the leapp upgrade command to run the system upgrade.

[root@host ~]# leapp upgrade

The Leapp tool first runs a final pre-upgrade analysis to identify potential problems with the upgrade. If the Leapp tool finds no issues during the analysis, then the Leapp tool downloads software packages and tests the RPM transaction for the upgrade.

After preparing the packages and other configurations, the Leapp tool prints the pre-upgrade report. Red Hat recommends that if any issues are reported, then you should not continue the upgrade until you have addressed all reported issues. Unresolved issues might affect applications or degrade system performance.

If the final pre-upgrade analysis does not find any errors, then the tool begins the actual upgrade. The Leapp tool also prints a message requesting a system reboot to continue with the upgrade.

[root@host ~]# leapp upgrade
...output omitted...
====> * add_upgrade_boot_entry
        Add new boot entry for Leapp provided initramfs.
A reboot is required to continue. Please reboot your system.


Debug output written to /var/log/leapp/leapp-upgrade.log

============================================================
                      REPORT OVERVIEW
============================================================
...output omitted...

This reboot enables the system to boot with a new RAM disk image with the new kernel.

The system continues the upgrade process after rebooting. Output from the Leapp tool is displayed on the console of the machine.

The Leapp tool then performs RPM transactions on the system, and when that is complete, it performs an SELinux relabel. Then the Leapp tool reboots the system to complete the upgrade and to ensure that the updated kernel and updated daemon processes are running.

You can review the contents of the /var/log/leapp/leapp-upgrade.log file for more information about the upgrade process. The following example shows an excerpt of an upgrade log file.

[root@host ~]# cat /var/log/leapp/leapp-upgrade.log
...output omitted...
2024-03-14 13:05:03.431 DEBUG    PID: 1381 leapp.repository.system_upgrade_common: Adding libraries - libraries
2024-03-14 13:05:03.444 DEBUG    PID: 1381 leapp.repository.system_upgrade_common: Adding tools - tools
2024-03-14 13:05:03.472 DEBUG    PID: 1381 leapp.repository.system_upgrade_el7toel8: Scanning path /etc/leapp/repos.d/system_upgrade/el7toel8
2024-03-14 13:05:03.487 DEBUG    PID: 1381 leapp.repository.system_upgrade_el7toel8: Adding model - models/authselect.py
2024-03-14 13:05:03.497 DEBUG    PID: 1381 leapp.repository.system_upgrade_el7toel8: Adding model - models/bindfacts.py
...output omitted...

You can also run the leapp upgrade command with options to adjust the command behavior for your environment.

[root@host ~]# leapp upgrade --target 8.8

[root@host ~]# leapp upgrade --enablerepo org-rhel-8-main \
--enablerepo org-rhel-8-additional

[root@host ~]# leapp upgrade --channel eus

If you experience problems during the upgrade, then use the --verbose and --debug options of the leapp upgrade command to display more detailed logs. By default, the Leapp tool only prints error and critical log messages.

Review the following files for more information about the upgrade process:

The following commands also provide additional information about the upgrade process:

You can use the logs from the previous lists as attachments when opening a support case. Make sure to include information that is relevant to the system and your upgrade plan.