Upgrade Oracle Linux with Leapp


The Leapp utility is a framework for updating and upgrading operating systems as well as applications. The utility’s component packages enable the creation of different workflows into profiles for updating software.

Leapp operations consist of two phases:

Leapp can be used to upgrade Oracle Linux 7 Oracle Cloud Infrastructure instances, as well as Oracle Linux 7 on premise systems.

This lab guides you through upgrading a current release Oracle Linux 7 Oracle Cloud Infrastructure instance to Oracle Linux 8.

Leapp is not supported for any other operating systems or versions.

Note: Before using Leapp in a production environment it is recommended to become familiar with the Leapp upgrade process in a test environment. This allows you to better understand the process, its reports, and test for any security or compatibility issues that might be encountered.


In this lab, you’ll learn to:


Note: You can view the full list of system and kernel prerequisites and preupgrade checks that should be made before upgrading with Leapp at this documentation link: Performing System Upgrades with Leapp.

Setup Lab Environment

When using the free lab environment, use this link to Oracle Linux Lab Basics to see how to establish an SSH connection and other usage instructions.

These sections show you how to make the SSH connection to the instance from the Terminal on your desktop.

Preparing for the Upgrade

The instance used in this lab has preconfigured settings specific to the environment, for example; proxy settings.

Some preupgrade checks normally carried out are skipped as they are not required in this environment.

Note: You can watch a free video demonstrating the Leapp upgrade process used in this lab. You will find the link at in the More Information section at the end of this lab.

  1. Establish an SSH connection to your lab system instance.

    Remember the link to Oracle Linux Lab Basics shows how to establish an SSH connection and other usage instructions.

  2. Verify that the system locale is set to en_US.UTF-8.

    cat /etc/locale.conf

    If the locale is not set correctly, use the command sudo localectl set-locale LANG=en_US.UTF-8 to configure this.

Update to latest packages

Update all system packages to the latest versions with Yum.

sudo yum update -y

This takes a few minutes, when the updates are completed, reboot the system.

sudo reboot

Wait a few minutes for the reboot to complete, then reconnect your SSH connection to the instance.

If the connection fails, wait a little longer and try again.

Install the Leapp Utility

Install the Leapp utility and its supporting repositories.

sudo yum install -y leapp --enablerepo=ol7_leapp,ol7_latest

Run the preupgrade check

The preupgrade process assesses if the system is prepared for a successful upgrade. It identifies potential issues that may affect or prevent the upgrade process.

The preupgrade check can be used anytime to assess the status of a system and identify where conflicts may occur. It does not change the system, but creates report files and a debug log, containing information about the system, its configuration, and potential upgrade issues.

  1. Run the leapp preupgrade command to start the preupgrade process.

    This lab system is a cloud instance so use the command switch --oci.

    sudo leapp preupgrade --oci

    If the system is a non cloud system, the switch --oraclelinux is used.

    The --oci and --oraclelinux are convenience switches used to preset repository and configuration information relevant to a cloud or non cloud system.

    • Example output:
                          UPGRADE INHIBITED                     
    Upgrade has been inhibited due to the following problems:  
        1. Inhibitor: Missing required answers in the answer file  
    Consult the pre-upgrade report for details and possible remediation.  
                       UPGRADE INHIBITED                        
    Debug output written to /var/log/leapp/leapp-preupgrade.log  
    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  

    A leapp-report.txt file and an answerfile are created, and debug information is saved in a leapp-preupgrade.log log file.

    In this lab environment, the onscreen result identifies one issue which will inhibit the upgrade. There may also be other non inhibiting issues in the files.

  2. Examine the leapp-report.txt file.

    sudo cat /var/log/leapp/leapp-report.txt

    Identify any high risk entries marked as Risk Factor: high (inhibitor). These will prevent an upgrade from completing.

    The report provides a summary of the issues and offers solutions to resolve them.

    This report is a useful introspection tool, providing a good view of what is configured in the system, what potential conflicts may exist, regardless of whether you will upgrade or not.

  3. Examine the answerfile.

    sudo cat /var/log/leapp/answerfile
    • Example output:
    # Title:              None  
    # Reason:             Confirmation  
    # =================== remove_pam_pkcs11_module_check.confirm ==================  
    # Label:              Disable pam_pkcs11 module in PAM configuration? If no, the upgrade process will be interrupted.  
    # Description:        PAM module pam_pkcs11 is no longer available in OL-8 since it was replaced by SSSD.  
    # Type:               bool  
    # Default:            None  
    # Available choices: True/False  
    # Unanswered question. Uncomment the following line with your answer  
    # confirm =  

    The Available Choices: True/False section informs how to modify the answerfile to address the issue found.

    Use the sudo leapp answer command to provide the answer True to the [remove_pam_pkcs11_module_check] PAM module item.

    sudo leapp answer --section remove_pam_pkcs11_module_check.confirm=True

    Note: If you prefer you can also edit the answerfile with the sudo vi /var/log/leapp/answerfile command and insert the True setting.

  4. Verify the answerfile has been modified.

    sudo cat /var/log/leapp/answerfile
    • Example output:
    confirm = True  

    Remember that all items in the answerfile, and any high risk Risk Factor: high (inhibitor) entries in the leapp-report.txt file must be resolved.

    You can run the preupgrade command anytime to generate the report files and ensure required items are addressed.

Upgrade the system

For comparison to after the upgrade, verify the current OS and kernel version of the system.

  1. Check the Oracle Linux version running on the system.

    sudo cat /etc/oracle-release
  2. Check the kernel version used.

    uname -r
  3. Run the upgrade process.

    sudo leapp upgrade --oci

    Note: The lab system is a cloud instance so the command switch --oci is used again.

    The upgrade process will take approximately 10 minutes, and returns to the command prompt when finished.

    • Example output:
    The downloaded packages were saved in cache until the next successful  
    You can remove cached packages by executing 'dnf clean packages'.  
    ==> Processing phase 'InterimPreparation'  
    ====> * efi_interim_fix  
           Adjust EFI boot entry for first reboot  
    ====> * initram_disk_generator  
           Creates the upgrade initram disk  
    ====> * 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  
    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  

    The upgrade process also updates the answerfile, leapp-report.txt, and creates a leapp-upgrade.log log file.

    Note: If you have not addressed the answerfile items and Risk Factor: high (inhibitor) entries in the leapp-report.txt file, the process will terminate back to command line and inform about the issues encountered.

  4. When the upgrade completes, reboot the system.

    sudo reboot

    The reboot will disconnect the SSH connection. During the boot process, the Leapp process automatically upgrades packages.

    The upgrade operation also includes multiple automatic reboots. You will not be able to reconnect the SSH session until all the reboots have completed.

    Wait approximately 15 minutes and then reconnect the SSH session to the system. If the connection fails, wait a few minutes and try again.

Verify the upgrade

Compare the OS version and kernel now used for the system with the preupgrade version.

  1. Check the Oracle Linux version running.

    sudo cat /etc/oracle-release
  2. Check the kernel version used.

    uname -r

    The upgrade is complete as you now see the system is running Oracle Linux 8.5 and the kernel used shows el8.

For More Information

See other related resources:

More Learning Resources

Explore other labs on or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.