Chapter 4. Manually upgrading small deployments

Procedure

1. On your RHEL 8 system, perform the pre-upgrade phase:

   # leapp preupgrade --target-version <_target_os_version_>

   Replace target_os_version with the target OS version, for example 9.6. If no target OS version is defined, Leapp uses the default target OS version specified in the table 1.1 in Supported upgrade paths.

   • If you are using custom repositories from the /etc/yum.repos.d/ directory for the upgrade, enable the selected repositories as follows:

     # leapp preupgrade --enablerepo <repository_id1> --enablerepo <repository_id2> ...

   • If you are upgrading without RHSM or by using RHUI, add the --no-rhsm option.
   • If you have an Extended Upgrade Support (EUS), Advanced Update Support (AUS), or Update Services for SAP Solutions (E4S) (Red Hat Knowledgebase) subscription, add the --channel <channel> option. Replace <channel> with the channel name, for example, eus, aus, or e4s. Note that SAP HANA customers must perform the in-place upgrade by using the Upgrading SAP environments from RHEL 8 to RHEL 9 guide.

   • If you are using RHEL for Real Time or the Real Time for Network Functions Virtualization (NFV) in your Red Hat OpenStack Platform, enable the deployment by using the --enablerepo option. For example:

     # leapp preupgrade --enablerepo rhel-9-for-x86_64-rt-rpms

     For more information, see Configuring Real-Time Compute.

2. Examine the report in the /var/log/leapp/leapp-report.txt file and manually resolve all the reported problems. Some reported problems contain remediation suggestions. Inhibitor problems prevent you from upgrading until you have resolved them.

   The report contains the following risk factor levels:

   High

   Very likely to result in a deteriorated system state.

   Medium

   Can impact both the system and applications.

   Low

   Should not impact the system but can have an impact on applications.

   Info

   Informational with no expected impact to the system or applications.

3. In certain system configurations, the Leapp utility generates true or false questions that you must answer manually. If the pre-upgrade report contains a Missing required answers in the answer file message, complete the following steps:

   1. Open the /var/log/leapp/answerfile file and review the true or false questions.

   2. Manually edit the /var/log/leapp/answerfile file, uncomment the confirm line of the file by deleting the # symbol, and confirm your answer as True or False. For more information, see the Leapp answerfile.

      Note

      Alternatively, you can answer the true or false question by running the following command:

      # leapp answer --section <question_section>.<field_name>=<answer>

      For example, to confirm a True response to the question Are all VDO devices, if any, successfully converted to LVM management?, execute the following command:

      # leapp answer --section check_vdo.confirm=True

4. Repeat the previous steps to rerun the pre-upgrade report to verify that you have resolved all critical issues.

Procedure

1. Install the cockpit-leapp plug-in:

   # dnf install cockpit-leapp

2. Log in to the web console as root or as a user that has permissions to enter administrative commands with sudo. See Managing systems using the RHEL 8 web console for more information about the web console.

3. On your RHEL 8 system, perform the pre-upgrade phase either from the command line or from the web console terminal:

   # leapp preupgrade --target-version <target_os_version>

   Replace target_os_version with the target OS version, for example 9.6. If no target OS version is defined, Leapp uses the default target OS version specified in the table 1.1 in Supported upgrade paths.

   • If you are using custom repositories from the /etc/yum.repos.d/ directory for the upgrade, enable the selected repositories as follows:

     # leapp preupgrade --enablerepo <repository_id1> --enablerepo <repository_id2> ...

   • If you are upgrading without RHSM or by using RHUI, add the --no-rhsm option.
   • If you have an Extended Upgrade Support (EUS), Advanced Update Support (AUS), or Update Services for SAP Solutions (E4S) subscription, add the --channel <channel> option. Replace <channel> with the channel name, for example, eus, aus, or e4s. Note that SAP HANA customers should perform the in-place upgrade using the Upgrading SAP environments from RHEL 8 to RHEL 9 guide.

   • If you are using RHEL for Real Time or the Real Time for Network Functions Virtualization (NFV) in your Red Hat OpenStack Platform, enable the deployment by using the --enablerepo option. For example:

     # leapp preupgrade --enablerepo rhel-9-for-x86_64-rt-rpms

     For more information, see Configuring Real-Time Compute.

4. In the web console, select Upgrade Report from the navigation menu to review all reported problems. Inhibitor problems prevent you from upgrading until you have resolved them. To view a problem in detail, select the row to open the Detail pane.

   Figure 4.1. In-place upgrade report in the web console

   

   The report contains the following risk factor levels:

   High

   Very likely to result in a deteriorated system state.

   Medium

   Can impact both the system and applications.

   Low

   Should not impact the system but can have an impact on applications.

   Info

   Informational with no expected impact to the system or applications.

5. In certain configurations, the Leapp utility generates true or false questions that you must answer manually. If the Upgrade Report contains a Missing required answers in the answer file row, complete the following steps:

   1. Select the Missing required answers in the answer file row to open the Detail pane. The default answer is stated at the end of the remediation command.
   2. To confirm the default answer, select Add to Remediation Plan to execute the remediation later or Run Remediation to execute the remediation immediately.

   3. To select the non-default answer instead, execute the leapp answer command in the terminal, specifying the question you are responding to and your confirmed answer.

      # leapp answer --section <question_section>.<field_name>=<answer>

      For example, to confirm a True response to the question Are all VDO devices, if any, successfully converted to LVM management?, execute the following command:

      # leapp answer --section check_vdo.confirm=True

      Note

      You can also manually edit the /var/log/leapp/answerfile file, uncomment the confirm line of the file by deleting the # symbol, and confirm your answer as True or False. For more information, see the Leapp answerfile example.

6. Some problems have remediation commands that you can run to automatically resolve the problems. You can run remediation commands individually or all together in the remediation command.

   1. To run a single remediation command, open the Detail pane for the problem and click Run Remediation.

   2. To add a remediation command to the remediation plan, open the Detail pane for the problem and click Add to Remediation Plan.

      Figure 4.2. Detail pane

      
   3. To run the remediation plan containing all added remediation commands, click the Remediation plan link in the top right corner above the report. Click Execute Remediation Plan to execute all listed commands.
7. After reviewing the report and resolving all reported problems, repeat steps 3-7 to rerun the report to verify that you have resolved all critical issues.

Procedure

1. On your RHEL 8 system, start the upgrade process:

   # leapp upgrade --target-version <_target_os_version_>

   Replace target_os_version with the target OS version, for example 9.6. If no target OS version is defined, Leapp uses the default target OS version specified in the table 1.1 in Supported upgrade paths.

   • If you are using custom repositories from the /etc/yum.repos.d/ directory for the upgrade, enable the selected repositories as follows:

     # leapp upgrade --enablerepo <repository_id1> --enablerepo <repository_id2> ...

   • If you are upgrading without RHSM or using RHUI, add the --no-rhsm option.
   • If you are upgrading by using an ISO image, add the --no-rhsm and --iso <file_path> options. Replace <file_path> with the file path to the saved ISO image, for example /home/rhel9.iso.
   • If you have an Extended Upgrade Support (EUS), Advanced Update Support (AUS), or Update Services for SAP Solutions (E4S) (Red Hat Knowledgebase) subscription, add the --channel channel option. Replace channel with the value you used with the leapp preupgrade command, for example, eus, aus, or e4s. Note that you must use the same value with the --channel option in both the leapp preupgrade and leapp upgrade commands.

   • If you are using RHEL for Real Time or the Real Time for Network Functions Virtualization (NFV) in your Red Hat OpenStack Platform, enable the deployment by using the --enablerepo option. For example:

     # leapp upgrade --enablerepo rhel-9-for-x86_64-rt-rpms

     For more information, see Configuring Real-Time Compute.

   • If you are upgrading with LiveMode, set the LEAPP_UNSUPPORTED=1 environment variable and use the --enable-experimental-feature option with the livemode value. For example:

     # LEAPP_UNSUPPORTED=1 leapp upgrade --enable-experimental-feature livemode

     For more information, see Configuring the upgrade with LiveMode.

     Important

     LiveMode is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

     For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

2. At the beginning of the upgrade process, Leapp performs the pre-upgrade phase described in Reviewing the pre-upgrade report.

   • If the system is upgradable, Leapp downloads necessary data and prepares an RPM transaction for the upgrade.
   • If your system does not meet the parameters for a reliable upgrade, Leapp terminates the upgrade process and provides a record describing the issue and a recommended solution in the /var/log/leapp/leapp-report.txt file. For more information, see Troubleshooting.

3. Manually reboot the system:

   # reboot

   The system boots into a RHEL 9-based initial RAM disk image, initramfs. Leapp upgrades all packages and automatically reboots to the RHEL 9 system.

   Alternatively, you can run the leapp upgrade command with the --reboot option and skip this manual step.

   If a failure occurs, investigate logs and known issues as described in Troubleshooting.

4. Log in to the RHEL 9 system and verify its state as described in Verifying the post-upgrade state.
5. Perform all post-upgrade tasks described in the upgrade report and in Performing post-upgrade tasks.