Back to the main page

Leapp tool for Linux in-place upgrade

Intro

Leapp is the utility for Linux (here Oracle Linux) in-place upgrades. The in-place upgrade is type of OS upgrade where earlier version (ex. OL7) is replaced with newer version (ex. OL8) without removing the earlier version first. The installed applications and utilities (this may vary), along with the OS configurations, are incorporated into the new version. This is different than traditional "clean install" upgrade, and data migration.
Current supported upgrades should be OL 7 to 8, and OL 8 to 9.

Test host

I'll be using the OCI Compute OL 7.9 (Image: Oracle-Linux-7.9-2024.01.23-0), and attempt in-place upgrade to OL 8.10. The host runs various applications like Apache Web server and Cobbler. I'll see how are they going to be upgraded.

In-place upgrade preparation

Current OS update

First update your current OL 7, run "yum update", you want to be on latest 7.9 (it's June 2024)

Install Leapp

Ensure you have Leapp yum repository, example baseurl=https://yum.oracle.com/repo/OracleLinux/OL7/leapp/x86_64
Install leapp-upgrade-el7toel8 package. Many other dependencies will be included.

Pre-upgrade check

For the pre-upgrade check, ensure there is 2 to 3 G in /var/lib/leapp folder. It should be enough space for leapp.db and other files. To generates preliminary pre-upgrade report, run the command:
$ leapp preupgrade

There will be message that upgrade is inhibited by some of problems, resolve them first. In this example, potential resolutions are:

- Since ksplice does in-memory updates, reboot the host to implement on-disk updates.
- Un-mount NFS shares. It maybe your home, log out, and login as root.
- Missing yum repository, we'll provide them in next run.
- Missing answers for un-attended upgrade. See /var/log/leapp/leapp-report.txt for resolution. You can provide answers in the file /var/log/leapp/answerfile.

The previous preliminary check is not mandatory, it's just convenient to resolve 'easy' problem upfront. Now run final check:

- Specify target (ex. 8.10, likely Leapp will go for it by default)
- Specify yum repositories for OL8. Do educated guess for what you need:
- If you use ksplice, ensure you have its repo.
- If kernel is UEK, you'll need that one also.
- Here we have EPEL, since Cobbler should be there.
- For variety of other tools, you may need addons.

$ leapp preupgrade  \
  --target 8.10  \
  --enablerepo ol8_baseos_latest --enablerepo ol8_UEKR6 \
  --enablerepo ol8_addons --enablerepo ol8_ksplice \
  --enablerepo ol8_appstream --enablerepo ol8_EPEL \
  --enablerepo ol8_oci_included

If there is no major problems, expect to see successful check finish with report:

Debug output written to /var/log/leapp/leapp-preupgrade.log
============================================================
                           REPORT
============================================================
A report has been generated at /var/log/leapp/leapp-report.json
A report has been generated at /var/log/leapp/leapp-report.txt
============================================================
                       END OF REPORT
============================================================
Answerfile has been generated at /var/log/leapp/answerfile

Review Risk Factor Levels in the file /var/log/leapp/leapp-report.txt. The level can be high, medium, low and info.
The Leapp documentation reads that 'high' = "Very likely to result in a deteriorated system state".
Some of high risks are "Diff in Python ver and support in OL8", "Some OL 7 pkgs have not been upgraded", "Packages not signed by Oracle found on host", and they may not be so risky for your use case.

Upgrade

Finally, run the upgrade. Replace the option 'preupgrade' with 'upgrade'.
Ensure you have the console connection, and follow the upgrade progress on the host's console.
$ leapp upgrade  \
  --target 8.10  \
  --enablerepo ol8_baseos_latest --enablerepo ol8_UEKR6 \
  --enablerepo ol8_addons --enablerepo ol8_ksplice \
  --enablerepo ol8_appstream --enablerepo ol8_EPEL \
  --enablerepo ol8_oci_included

At this point, you are required to reboot the host. Follow the progress on the console.

Transaction test succeeded.
Complete!
====> * 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
============================================================
A report has been generated at /var/log/leapp/leapp-report.json
A report has been generated at /var/log/leapp/leapp-report.txt
============================================================
                       END OF REPORT
============================================================
Answerfile has been generated at /var/log/leapp/answerfile

Post upgrade review

This is the time to find out if you are satisfied with in-place upgrade.
In case of OCI compute, you'll still see OL7 image, but that's understandable.

For the OS itself, the upgrade has been almost successful. Note next:
- Some ol7 packages haven't been removed. Remove them with "dnf remove".
- If ol7 package is filtered out by exclude filtering argument in /etc/yum.conf, remove this exclude line, and remove the package via 'dnf remove'.
- Remove ol7 yum repos (if any) from /etc/yum.repos.d
- Run "dnf update", but likely no action is needed.
- The host's SSH keys remains same.
- Check applications:
- In case of Cobbler server, the Cobbler application wasn't upgraded from v2 to v3. This major upgrade is not supported by application (v2 available only on OL7, and v3 only on OL8), hence Leapp cannot help here.
- For example, Apache web server was successfully upgraded from 2.4.6 (latest for OL7) to 2.4.37 (latest for OL8).

Overall, it's good.

Back to the main page