3 Upgrading the System

This chapter discusses the different stages of a system upgrade, which are the assessment phase and the upgrade phase. The main commands to use for these stages are leapp preupgrade and leapp upgrade, and followed by command arguments. For a list of these arguments, use the -h or --help argument, for example: 

sudo leapp preupgrade --help

Assessing the Capability of the System for Upgrading

The preupgrade phase checks whether the system is fully ready for the upgrade.

Important:

Refer also to Known Issues to better prepare the system for a Leapp upgrade.

Running the Preupgrade

Through the preupgrade phase, you can check whether the system is ready for the upgrade.

Running the preupgrade phase is recommended to ensure that the system is cleared of issues that might impede the upgrade. In this phase, you generate an assessment report that identifies risks to upgrading. The report also provides recommendations for resolving those risks.

  1. If you're using a proxy server, edit the /etc/yum.repos.d/leapp-upgrade-repos-ol10.repo by adding the proxy setting for each repository entry.

    To add the setting in a single operation, you can run the following command: 

    sudo sed -i '/^enabled=0.*/a proxy=http://proxy-host:proxy-port' /etc/yum.repos.d/leapp-upgrade-repos-ol10.repo

  2. Run the preupgrade command.

    Use the appropriate command argument for a system.

    • On a system: 

      sudo leapp preupgrade --oraclelinux [--enablerepo repository]

    For detailed information about the arguments, see Using Command Arguments to Enable Repositories.

    This process generates a process log, a report, and a answerfile file.

Analyzing the Leapp Report

The /var/log/leapp/leapp-report.txt identifies potential risks to the upgrade. The risks are classified as high, medium, or low. A high risk that would prevent an upgrade is further classified as an inhibitor. The report summarizes the issues behind the identified risk and also suggests remediations if any are needed.

Ensure that you complete the recommended remedies to clear risks that are labeled high and can inhibit the upgrade process.

After addressing the reported risks, run the preupgrade command again. In the regenerated report, verify that all serious risks are cleared.

To better illustrate the contents of the report, consider the examples in the following sections:

Legacy Network Configuration Issue

The report might warn about network configuration files using the legacy ifcfg format. 

Risk Factor: high (inhibitor)
Title: Legacy network configuration found
Summary: Network configuration files in legacy "ifcfg" format are present.In Oracle Linux 10, support for these files is no longer enabled and the configuration will be ignored. The following files were found:
    - /etc/sysconfig/network-scripts/ifcfg-ens3
Related links:
    - nmcli(1) manual, describes "connection migrate" sub-command.: https://networkmanager.dev/docs/api/latest/nmcli.html
    - nm-settings-ifcfg-rh(5), description of the "ifcfg" format: https://networkmanager.dev/docs/api/latest/nm-settings-ifcfg-rh.html
    - nm-settings-keyfile(5), description of the "keyfile" format: https://networkmanager.dev/docs/api/latest/nm-settings-keyfile.html

To resolve this issue, review the following instructions and suggestions: 

Remediation: [hint] Convert the configuration into NetworkManager native "keyfile" format.
[command] nmcli connection migrate /etc/sysconfig/network-scripts/ifcfg-ens3
ipa-server Package is Installed Without IdM Configured Issue

The report might warn about the free-ipa package. 

Risk Factor: medium 
Title: ipa-server package is installed but no IdM is configured
Summary: The ipa-server package is installed but neither IdM server nor client is configured on this system.
Related links:
    - IdM migration guide: https://docs.oracle.com/en/operating-systems/oracle-linux/10/leapp

To resolve this issue, review the following instructions and suggestions: 

Remediation: [hint] Remove ipa-server package and install it after in-place upgrade, if you need ipa-server functionality on upgraded system

Providing Information to the Leapp Answerfile

In addition to completing the recommendations of /var/log/leapp/leapp-report.txt, you must also provide answers to all the items in /var/log/leapp/answerfile.

An inhibitor might be reported both in /var/log/leapp/answerfile and /var/log/leapp/leapp-report.txt, with the latter file providing an alternative remedy. Despite overlapping contents, always examine both files to ensure a successful upgrade.

The /var/log/leapp/answerfile file consists of specific verification checks that Leapp performs on the system. A verification check contains information about the system and also prompts you for confirmation on the action to be performed. The file provides context and information to help guide you on the response required.

Note:

All verification checks listed in the answerfile must be answered. Unanswered items cause the upgrade process to halt.

To provide responses to answerfile, choose from one of the following methods:

  • Use the leapp answer command.

    Run this command on the specific section that needs correcting. For example, to confirm the PAM module verification, you would type: 

    sudo leapp answer --section remove_pam_pkcs11_module_check.confirm=True

  • Edit the contents of /var/log/leapp/answerfile.

    Go to the specific section that you want to confirm, such as [remove_pam_pkcs11_module_check], uncomment its confirm = line and specify the answer, for example: 

    confirm = True

Performing the Upgrade

After you have completed the /var/log/leapp/answerfile and verified that /var/log/leapp/leapp-report.txt no longer reports risks, upgrade the system as follows:

  1. Using a console, connect to the system that you're upgrading.

    • If you're upgrading a remote system configured with a VNC server, connect to the system by using a VNC client.

  2. On a separate terminal window of the system or instance to be upgraded, run the upgrade command with the appropriate command argument.

    • On a system: 

      sudo leapp upgrade --oraclelinux [--enablerepo repository]

    For detailed information about the command arguments, see Using Command Arguments to Enable Repositories.

  3. Verify that the report summary returns no errors or inhibitors. For example, the following report shows no errors or inhibitors: 
    ============================================================
                      REPORT OVERVIEW                       
============================================================

HIGH and MEDIUM severity reports:
    1. Packages not signed by Oracle found on the system
    2. Default Boot Kernel
    3. Berkeley DB (libdb) has been detected on your system
    4. PostgreSQL (postgresql-server) has been detected on your system
    5. Manual migration of data from MySQL database might be needed

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

Before continuing, review the full report below for details about discovered problems and possible remediation instructions:
    A report has been generated at /var/log/leapp/leapp-report.txt
    A report has been generated at /var/log/leapp/leapp-report.json

============================================================
                   END OF REPORT OVERVIEW                   
============================================================

    If any errors or inhibitors appear, resolve them before rebooting the system and rerun the Leapp upgrade.

  4. Reboot the system. 

    sudo reboot

  5. While the system reboots, monitor the progress on the console.

    At the completion of the boot process, the utility automatically proceeds with upgrading packages. This operation takes awhile to complete and also includes multiple automatic reboots.

    Caution:

    Do not interrupt the ongoing processes at this stage. Wait until the login screen appears, which indicates that the entire upgrade process has completed. Only then can you begin to use the system.

  6. When the login screen appears on the console, log in with the proper credentials.

Important:

See Oracle Linux 10 documentation for information about new features, changes, and deprecated items in Oracle Linux 10. Thus, you can identify post upgrade tasks that you might need to complete.

Verifying the Upgrade

Upon completion, the upgrade process generates the same files as the preupgrade phase: a process log, a report, and the /var/log/leapp/answerfile. On a terminal, perform the following steps:

  1. Examine the /var/log/leapp/leapp-report.txt and fulfill any important recommendations to be completed after the upgrade process.

  2. Perform the following verifications:

    To verify the system's new OS version, type: 

    cat /etc/oracle-release

    To check the system's kernel version, type this command to verify that the kernel contains the el10 substring: 

    uname -r

    You can also identify the system's default kernel with the following command: 

    sudo grubby --default-kernel