Upgrading the System

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

If you're using a proxy server, edit the /etc/yum.repos.d/leapp-upgrade-repos-ol9.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-ol9.repo 
```
Run the preupgrade command.

Use the appropriate command argument for a system or an Oracle Cloud Infrastructure instance.
- On a system:
```
sudo leapp preupgrade --oraclelinux [--enablerepo repository]
```
- On an instance in Oracle Cloud Infrastructure:
```
sudo leapp preupgrade --oci [--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 file called answerfile.

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 following examples:

GPG Key Issue

The report might warn about the gpg-pubkey.

Risk Factor: high 
Title: Packages not signed by Oracle found on the system 
Summary: The following packages have not been signed by Oracle and may be 
removed during the upgrade process in case Oracle-signed packages to be removed 
during the upgrade depend on them: 
- gpg-pubkey

To resolve this issue, run the following command:

sudo rpm -qa | grep gpg-pubkey

If the command output lists only the Oracle Linux 8 public key gpg-pubkey-ec551f03-53619141, the issue can be ignored. Otherwise, any other unsigned packages or gpg-pubkey entries in the report must be manually analyzed, as they might be removed during the upgrade.

Btrfs File System Issue

On aarch64 systems, the Leapp report might report the following:

Title: UEKR6 has been found and BTRFS filesystem is in use.
Summary: Upgrade process was interrupted because btrfs is enabled
         and UEKR6 has been found.

The page size for aarch64 systems has changed from 64 KB to 4 KB in UEK R7. For more information about issues that involve this feature, see the list of Arm Features in Oracle Linux 9 in Oracle Linux 9: Release Notes for Oracle Linux 9.

If the aarch64 system that's running UEK R6 is configured with the Btrfs file system, then you can't use Leapp to upgrade to Oracle Linux 9. For more information about issues that involve upgrading aarch64 systems that use the Btrfs file system, see Unbreakable Enterprise Kernel Release 7: Release Notes (5.15.0-0.30).

If your aarch64 system is running UEK R6 but does not use the Btrfs file system, then, for the upgrade to proceed, confirm, and accept the page size change that takes effect because of the upgrade. You can confirm the page size change in the answer file or by running the following command:

leapp answer --section confirm_UEKR7_install_pagesize_4k.confirm=True

However, if the Oracle Linux 8 aarch64 system is already running UEK R7, then the upgrade to Oracle Linux 9 proceeds normally. No confirmation of the page change is required.

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.

The following is a sample entry from /var/log/leapp/answerfile:

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

Based on the example, each verification check is identified with a section heading in square brackets, such as remove_pam_pkcs11_module_check. The heading is followed by descriptions of the issue and the valid responses to address the issue.

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:

Using a console, connect to the system or the Oracle Cloud Infrastructure instance 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.
- If you're working on an Oracle Cloud Infrastructure instance, connect to the instance through the console connection you previously created in Preparing for the Upgrade. For instructions, see Connecting to the Serial Console in https://docs.oracle.com/iaas/Content/Compute/References/serialconsole.htm#Instance_Console_Connections .
  
  For example, on a local terminal window, the command that's provided to connect to the instance might resemble the following syntax:
```
ssh -o ProxyCommand='ssh additional-commands
```
  If the command doesn't work at first use, you might need to specify the -i path-to-key option, for example:
```
ssh -i path-to-key -o ProxyCommand='ssh -i path-to-key additional-commands
```
  Because OCI requests only rsa keys, on some systems, you might need to add the following in the /etc/ssh/ssh_config directory:
```
HostkeyAlgorithms +ssh-rsa
PubkeyAcceptedAlgorithms +ssh-rsa 
```
On a separate terminal window of the system or instance to be upgraded, run the upgrade command with the appropriate command argument, depending on whether you're upgrading a system or an Oracle Cloud Infrastructure instance.
- On a system:
```
sudo leapp upgrade --oraclelinux [--enablerepo repository]
```
- On an instance in Oracle Cloud Infrastructure:
```
sudo leapp upgrade --oci [--enablerepo repository]
```
For detailed information about the command arguments, see Using Command Arguments to Enable Repositories.

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

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

=========================================== REPORT OVERVIEW
===========================================
HIGH and MEDIUM severity reports:
    1. Using repository not supported by Oracle
    2. OSWatcher is removed from OL9.
    3. Packages not signed by Oracle found on the system
    4. Default Boot Kernel
    5. PostgreSQL (postgresql-server) has been detected on your system
    6. Managed instance upgrade requires user to accept certain requirements for OS Management Service
    7. Managed instance upgrade requires user to accept certain requirements for used Software Source.

Reports summary:
    Errors: 0
    Inhibitors: 0
    HIGH severity reports: 3
    MEDIUM severity reports: 4
    LOW severity reports: 1
    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

If any errors or inhibitors appear, resolve them before rebooting the system.

Reboot the system.
```
sudo reboot
```
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.
When the login screen appears on the console, log in with the proper credentials.

After the completion of an instance upgrade, the instance retains its Oracle Linux 8 base image on the Instance Details page of the Oracle Cloud Infrastructure console, for example, Oracle-Linux-8.6-2022.05-27-0. You can apply a custom tag so you can track the upgrades that have been performed on the instance after its creation.

Important:

See Oracle Linux 9 documentation for information about new features, changes, and deprecated items in Oracle Linux 9. 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:

Examine the /var/log/leapp/leapp-report.txt and fulfill any important recommendations to be completed after the upgrade process.
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 el9 substring:
```
uname -r
```
You can also identify the system's default kernel with the following command:
```
sudo grubby --default-kernel
```