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.

Grant root SSH login permissions in the /etc/ssh/sshd_config file.
```
PermitRootLogin yes
```
If you're using a proxy server, edit the /etc/yum.repos.d/leapp-upgrade-repos-ol8.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-ol8.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 that is not running the OSMS agent:
```
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:

Python Version Issue

The Leapp report might post the following:

Risk Factor: high
Title: Difference in Python versions and support in OL 8
Summary: In OL 8, there is no 'python' command. Python 3 (backward incompatible)
 is the primary Python version and Python 2 is available with limited support an
d limited set of packages. Read more here: https://docs.oracle.com/en/operating-
systems/oracle-linux/8/python/
Remediation: [hint] Please run "alternatives --set python /usr/bin/python3" after upgrade

As the example shows, for some risks, the report would suggest actions you should perform after the upgrade. Therefore, the risk, although high, is not labeled as an inhibitor. The remedy can be performed later.

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 7 public key gpg-pubkey-ec551f03-53619141, the issue can be safely 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.

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

Note:

Systems that use the Btrfs file system must also confirm in /var/log/leapp/answerfile the switch to using UEK. As noted in Kernels Upgradeable With Leapp, using the Btrfs file system in Oracle Linux 8 requires the UEK kernel. To confirm the kernel upgrade, issue this command to update answerfile:

sudo leapp answer --section confirm_UEK_install_and_default_boot_kernel.confirm=True

Alternatively, you can edit the specific section in answerfile.

Performing the Upgrade

After you have properly 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
```
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 that is not running OSMS agent:
```
sudo leapp upgrade --oci [--enablerepo repository]
```
For detailed information about the command arguments, see Using Command Arguments to Enable Repositories.
At the end of the upgrade, 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 7 base image on the Instance Details page of the Oracle Cloud Infrastructure console, for example, Oracle-Linux-7.9-2020-11.10-1. 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 8 documentation for information about new features, changes, and deprecated items in Oracle Linux 8. Thus, you can identify post upgrade tasks that you might need to complete. For example, after the upgrade, network configurations and settings from Oracle Linux 7 continue to operate based on legacy network scripts. However, network scripts are deprecated in Oracle Linux 8. Therefore, consider reconfiguring the upgraded system's network settings to be managed by NetworkManager. For more information, see Oracle Linux 8: Setting Up Networking.

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 the console, 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 el8 substring:
```
uname -r
```
You can also identify the system's default kernel with the following command:
```
sudo grubby --default-kernel
```