Upgrade Oracle Linux with Leapp

Introduction

The Leapp utility is a framework for updating and upgrading operating systems and 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 Oracle Cloud Infrastructure instances, as well as Oracle Linux on-premise systems.

This tutorial functions in two parts:

It guides you through upgrading an Oracle Linux 7 instance to Oracle Linux 8.
It guides you through upgrading the same system from Oracle Linux 8 to Oracle Linux 9.

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, and its reports, and test for any security or compatibility and pre and post-upgrade issues that might be encountered.

Note: The Leapp utility is used to upgrade the Operating System (OS) only, for example, from the current Oracle Linux 7 release to the current Oracle Linux 8, or the current Oracle Linux 8 to the current Oracle Linux 9. The procedures in this tutorial do not apply to and are unsupported on any other OS or versions.

Objectives

In this tutorial, you'll learn to:

Prepare an Oracle Linux 7 system to use Leapp to upgrade to Oracle Linux 8, then prepare the same system to upgrade to Oracle Linux 9
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
Use the Leapp utility to perform an upgrade of the system to Oracle Linux 8 and then perform another upgrade of the same system to Oracle Linux 9

Prerequisites

An Oracle Linux instance running the latest release of Oracle Linux 7

Deploy Oracle Linux

Note: If running in your own tenancy, read the linux-virt-labs GitHub project README.md and complete the prerequisites before deploying the lab environment.

Open a terminal on the Luna Desktop.

Clone the linux-virt-labs GitHub project.

git clone https://github.com/oracle-devrel/linux-virt-labs.git

Change into the working directory.
```
cd linux-virt-labs/ol
```

Install the required collections.

ansible-galaxy collection install -r requirements.yml

Deploy the lab environment.
```
ansible-playbook create_instance.yml -e localhost_python_interpreter="/usr/bin/python3.6" -e os_version="7.9"
```
The free lab environment requires the extra variable local_python_interpreter, which sets ansible_python_interpreter for plays running on localhost. This variable is needed because the environment installs the RPM package for the Oracle Cloud Infrastructure SDK for Python, located under the python3.6 modules.
The default deployment shape uses the AMD CPU and Oracle Linux 8. To use an Intel CPU or Oracle Linux 9, add -e instance_shape="VM.Standard3.Flex" or -e os_version="9" to the deployment command.
Important: Wait for the playbook to run successfully and reach the pause task. At this stage of the playbook, the installation of Oracle Linux is complete, and the instances are ready. Take note of the previous play, which prints the public and private IP addresses of the nodes it deploys and any other deployment information needed while running the lab.

Preparing for the Upgrade from Oracle Linux 7 to Oracle Linux 8

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.

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: Oracle Linux 8 - Performing System Upgrades with Leapp

Open a terminal and connect via SSH to the ol-node-01 instance.
```
ssh oracle@<ip_address_of_instance>
```
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.

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

For information on preupgrade preparation steps you may need to run on your own systems, see Preparing for the Upgrade in the Oracle documentation.

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:

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

============================================================
                      REPORT OVERVIEW                       
============================================================

Upgrade has been inhibited due to the following problems:
    1. Possible problems with remote login using root account
    2. Missing required answers in the answer file

HIGH and MEDIUM severity reports:
    1. Difference in Python versions and support in OL 8
    2. Detected customized configuration for dynamic linker.
    3. Default Boot Kernel

Reports summary:
    Errors:                      0
    Inhibitors:                  2
    HIGH severity reports:       2
    MEDIUM severity reports:     1
    LOW severity reports:        5
    INFO severity reports:       2

Before continuing consult the full 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 OVERVIEW                   
============================================================

Answerfile has been generated at /var/log/leapp/answerfile

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

In this environment, under the section Reports summary:, Inhibitors: indicates there are two issues which will inhibit the upgrade. There are also other non-inhibiting severity issues listed as HIGH, MEDIUM, LOW and INFO which should be addressed but will not prevent the upgrade.

These are also detailed in the leapp-report text and JSON files.

Examine the leapp-report.txt file.
```
sudo cat /var/log/leapp/leapp-report.txt
```
Identify the 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 and what potential conflicts may exist, regardless of whether you will upgrade or not.
Clear the first inhibitor by editing the /etc/ssh/sshd_config to uncomment the PermitRootLogin entry and add a new PermitRootLogin prohibit-password entry.
```
sudo sed -i 's/#PermitRootLogin yes/PermitRootLogin yes/;/PermitRootLogin yes/a PermitRootLogin prohibit-password' /etc/ssh/sshd_config
```
Examine the /etc/ssh/sshd_config file to confirm the new settings.
```
sudo cat /etc/ssh/sshd_config
```
Verify the two entries are present and enabled.
- Example output:
```
.   
# Authentication:

#LoginGraceTime 2m
PermitRootLogin yes
PermitRootLogin prohibit-password
#StrictModes yes
#MaxAuthTries 6
#MaxSessions 10
.
```
Note: If you prefer you can also edit the sshd_config with the sudo vi /etc/ssh/sshd_config command and add the two settings.

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 must be answered, 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 that the required items are addressed.

Repeat the preupgrade command to verify there are no inhibitors to prevent the upgrade. The Inhibitors: line should show 0 before you can proceed to upgrade.

Example output:

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

============================================================
                      REPORT OVERVIEW                       
============================================================

HIGH and MEDIUM severity reports:
    1. Detected customized configuration for dynamic linker.
    2. Difference in Python versions and support in OL 8
    3. Module pam_pkcs11 will be removed from PAM configuration
    4. Default Boot Kernel

Reports summary:
    Errors:                      0
    Inhibitors:                  0
    HIGH severity reports:       2
    MEDIUM severity reports:     2
    LOW severity reports:        5
    INFO severity reports:       2

Before continuing consult the full 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 OVERVIEW                   
============================================================

Answerfile has been generated at /var/log/leapp/answerfile

Upgrade the system

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

Check the Oracle Linux version that is 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:

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

HIGH and MEDIUM severity reports:
    1. Difference in Python versions and support in OL 8
    2. Detected customized configuration for dynamic linker.
    3. Module pam_pkcs11 will be removed from PAM configuration
    4. Default Boot Kernel

Reports summary:
    Errors:                      0
    Inhibitors:                  0
    HIGH severity reports:       2
    MEDIUM severity reports:     2
    LOW severity reports:        5
    INFO severity reports:       2

Before continuing consult the full 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 OVERVIEW                   
============================================================

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 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 the 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 been 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
```
With the upgrade complete you now see the system is running Oracle Linux 8.x and the kernel version shows el8.

Following the upgrade and any changes made by the process, it is important to ensure that the upgraded system remains in a supported state.

For information and guidance for procedures and checks to help return the upgraded system back into operation, see postupgrade information in the documentation.

This is recommended reading for Leapp upgrades performed on your own systems.

Upgrade from Oracle Linux 8 to Oracle Linux 9

You will now use Leapp again to upgrade your lab system from Oracle Linux 8 to Oracle Linux 9.

Note: The Leapp utility used is specific to the Oracle Linux version you wish to upgrade. You must install the correct utility for the OS version you will run it on.

Note: The Leapp utility is used to upgrade the Operating System only, for example, from the current Oracle Linux 8 release to the current Oracle Linux 9 version. The procedures in this tutorial do not apply to and are unsupported on any other OS or versions.

Preparing for the Upgrade from Oracle Linux 8 to Oracle Linux 9

Before you use Leapp again to upgrade your system to Oracle Linux 9, some preparations needed following the previous upgrade.

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: Oracle Linux 9 - Performing System Upgrades with Leapp

Update all system packages to the latest versions.
```
sudo dnf update -y
```
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.

Edit /etc/dnf/dnf.conf to comment out the exclude= line that refers to leapp packages.

sudo sed -i 's/exclude=python2-leapp,snactor,leapp-upgrade-el7toel8,leapp/#exclude=python2-leapp,snactor,leapp-upgrade-el7toel8,leapp/' /etc/dnf/dnf.conf

Install the NetworkManager package, then unmask and start the service. Run these commands in this order.

sudo dnf install -y NetworkManager 
sudo systemctl unmask NetworkManager 
sudo systemctl start NetworkManager 
sudo systemctl enable NetworkManager

Remove any kernels, kernel modules and residual packages that are no longer applicable. Search for any with el7 in the name.

sudo rpm -qa | grep el7

Example output:

python2-leapp-0.17.0-1.0.2.el7_9.noarch
kernel-uek-5.4.17-2136.336.5.1.el7uek.x86_64
kernel-uek-5.4.17-2136.338.4.1.el7uek.x86_64
leapp-0.17.0-1.0.2.el7_9.noarch
kernel-3.10.0-1160.119.1.0.5.el7.x86_64
leapp-upgrade-el7toel8-0.20.0-2.0.5.el7_9.noarch

Note: The filenames you see in your lab may differ from the ones shown in the example output here.

sudo dnf remove -y leapp-upgrade
sudo dnf remove -y python2-leapp
sudo dnf remove -y *el7*

Note: If you see errors preventing the removal of the Leapp packages, verify you made the earlier edit to the dnf.conf file.

Clean all items from the DNF cache.
```
sudo dnf clean all
```

Install the Leapp utility for Oracle Linux 8 and run the preupgrade check

The Leapp utility used is specific to the OS to be upgraded, so it is necessary to install the Oracle Linux 8 version of the Leapp utility. This is why you previously removed any old Leapp packages remaining from the previous upgrade.

Install the Oracle Linux 8 Leapp utility.

sudo dnf install -y leapp-upgrade

Run the preupgrade check

For information on preupgrade preparation steps you may need to run on your own systems, see Preparing for the Upgrade in the Oracle documentation.

Run the leapp preupgrade command to test the upgrade process and report any inhibitors.

Again for this cloud instance, we use the command switch --oci.

sudo leapp preupgrade --oci

Example output:


============================================================
                      REPORT OVERVIEW                       
============================================================

Upgrade has been inhibited due to the following problems:
    1. Firewalld Configuration AllowZoneDrifting Is Unsupported
    2. Network configuration with disabled NetworkManager support detected
    3. OSWatcher is removed from OL9.
    4. Missing required answers in the answer file

HIGH and MEDIUM severity reports:
    1. Remote root logins globally allowed using password
    2. Packages not signed by Oracle found on the system
    3. Default Boot Kernel

Reports summary:
    Errors:                      0
    Inhibitors:                  4
    HIGH severity reports:       2
    MEDIUM severity reports:     1
    LOW severity reports:        1
    INFO severity reports:       3

Before continuing consult the full 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 OVERVIEW                   
============================================================

Check the output in the Reports summary: section for any inhibitors.

Also, examine the /var/log/leapp/leapp-report.txt for any inhibitor entries and /var/log/leapp/answerfile for any unanswered entries.

Clear the inhibitors

In this environment, certain inhibitors are present following the previous upgrade from Oracle Linux 7 to Oracle Linux 8.

A post-upgrade system check would typically address issues before you return your system to operation.

Use the following commands to clear these inhibitors.

Enable NetworkManager support for network interface configuration on your lab system.

sudo sed -i 's/NM_CONTROLLED=no/NM_CONTROLLED=yes/' /etc/sysconfig/network-scripts/ifcfg-ens3

Disable AllowZoneDrifting in the firewall configuration file /etc/firewalld/firewalld.conf to prevent the Leapp upgrade from being blocked.
```
sudo sed -i 's/^AllowZoneDrifting=.*/AllowZoneDrifting=no/' /etc/firewalld/firewalld.conf
```
Answer the OSWatcher entry in the /var/log/leapp/answerfile. This will also address the second OSWatcher entry in the leapp-report.txt file.
```
sudo leapp answer --section update_oswatcher_to_pcp.confirm=True
```

Run the preupgrade command again to verify there are no more inhibitors in your report output.

In this environment, there will still be some items listed in the Reports summary.

Only continue forward to upgrading the system when the Inhibitors: line shows 0.

Upgrade the system

Verify the current Oracle Linux 8 OS version and kernel before upgrading.

Check the Oracle Linux version and kernel running before upgrading.

sudo cat /etc/oracle-release
uname -r

Run the upgrade process.

sudo leapp upgrade --oci

When the upgrade completes, reboot the system.

sudo reboot

The system will reboot multiple times. 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

Verify the upgraded Oracle Linux 9 version and kernel are now used for your system.

sudo cat /etc/oracle-release
uname -r

The upgrade is complete and the system is running Oracle Linux 9.x and the kernel version shows el9.

For information and guidance for procedures and checks to help return the upgraded system back into operation, see postupgrade information in the documentation.

This is recommended reading for Leapp upgrades performed on your own systems.

Next Steps

By completing this tutorial, you have demonstrated your skills and ability to use Leapp utility to upgrade Oracle Linux systems.

When running Leapp on your own systems remember to review the post-upgrade documentation to ensure the systems remain in a supported state.

Upgrade Oracle Linux with Leapp

Introduction

Objectives

Prerequisites

Deploy Oracle Linux

Preparing for the Upgrade from Oracle Linux 7 to Oracle Linux 8

Update to latest packages

Install the Leapp Utility

Run the preupgrade check

Upgrade the system

Verify the upgrade

Upgrade from Oracle Linux 8 to Oracle Linux 9

Preparing for the Upgrade from Oracle Linux 8 to Oracle Linux 9

Install the Leapp utility for Oracle Linux 8 and run the preupgrade check

Run the preupgrade check

Clear the inhibitors

Upgrade the system

Verify the upgrade

Next Steps

Related Links