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

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:
```
sudo leapp preupgrade --oci [--enablerepo repository]
```
Note:

If you're upgrading Oracle Linux 7 system to Oracle Linux 8 system on OCI and want to have NetworkManager installed and managing connections after the upgrade, set the LEAPP_OCI_NM=1 environment variable before running an in-place upgrade. Because Oracle Linux 7 is in Extended Support, use this feature only if you have specific workflows depending on NetworkManager being installed and managing connections post upgrade.

For example, you can set the environment variable while running the command:
```
LEAPP_OCI_NM=1 leapp preupgrade --oci
```
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:

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

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 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]
```
Note:

If you're upgrading Oracle Linux 7 system to Oracle Linux 8 system on OCI and want to have NetworkManager installed and managing connections after the upgrade, set the LEAPP_OCI_NM=1 environment variable before running an in-place upgrade. Because Oracle Linux 7 is in Extended Support, use this feature only if you have specific workflows depending on NetworkManager being installed and managing connections post upgrade.

For example, you can set the environment variable while running the command:
```
LEAPP_OCI_NM=1 leapp upgrade --oci
```
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:
If any errors or inhibitors appear, resolve them before rebooting the system and rerun the Leapp 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 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 el8 substring:
```
uname -r
```
You can also identify the system's default kernel with the following command:
```
sudo grubby --default-kernel
```

3 Upgrading the System