Note:

This tutorial is available in an Oracle-provided free lab environment.
It uses example values for Oracle Cloud Infrastructure credentials, tenancy, and compartments. When completing your lab, substitute these values with ones specific to your cloud environment.

Upgrade Oracle Linux with Leapp

Introduction

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:

Preupgrade - a process that examines many aspects of the system and runs checks to determine if the OS software can be upgraded.
Upgrade - updates the system based on configuration files that map packages between previous and current versions of the software.

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.

Objectives

In this lab, you’ll learn to:

Prepare an Oracle Linux 7 system and use Leapp to upgrade to Oracle Linux 8
Check and modify prerequisite settings to the system to support the Leapp upgrade
Perform a preupgrade check to inspect and create reports on the system configuration and items to be addressed before upgrading
Perform an upgrade of the system to Oracle Linux 8 using the Leapp utility

Prerequisites

An Oracle Cloud Infrastructure instance running the current release Oracle Linux 7

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.

Copy Public IP Address
Connect to Oracle Linux Instance

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.

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

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  
                                                            
============================================================  
                         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  

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.

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.

Examine the answerfile.

sudo cat /var/log/leapp/answerfile

Example output:

[remove_pam_pkcs11_module_check]  
# 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.

Verify the answerfile has been modified.
```
sudo cat /var/log/leapp/answerfile
```
- Example output:
```
[remove_pam_pkcs11_module_check]  
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.

Check the Oracle Linux version running on the system.
```
sudo cat /etc/oracle-release
```
Check the kernel version used.
```
uname -r
```

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  
transaction.  
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  
  
============================================================  
                          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  

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.

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.

Check the Oracle Linux version running.
```
sudo cat /etc/oracle-release
```
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:

Video: Oracle Linux Upgrades with Leapp
Document: Oracle Linux 8 Performing System Upgrades With Leapp
Luna Labs: Linux OS and Virualization Engineering Labs
Learning Path: Working with Oracle Linux 8
Document: Oracle Linux Documentation

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.

Title and Copyright Information

Upgrade Oracle Linux with Leapp

F55519-04

October 2022