Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Upgrading from RHEL 8 to RHEL 9

Red Hat Enterprise Linux 9

Instructions for an in-place upgrade from Red Hat Enterprise Linux 8 to Red Hat Enterprise Linux 9

Red Hat Customer Content Services

Abstract

This document provides instructions on how to perform an in-place upgrade from Red Hat Enterprise Linux 8 to Red Hat Enterprise Linux 9 using the Leapp utility. During the in-place upgrade, the existing RHEL 8 operating system is replaced by a RHEL 9 version.

Providing feedback on Red Hat documentation
Copy link

We appreciate your feedback on our documentation. Let us know how we can improve it.

Submitting feedback through Jira (account required)

  1. Log in to the Jira website.
  2. Click Create in the top navigation bar
  3. Enter a descriptive title in the Summary field.
  4. Enter your suggestion for improvement in the Description field. Include links to the relevant parts of the documentation.
  5. Click Create at the bottom of the dialogue.

Key migration terminology
Copy link

While the following migration terms are commonly used in the software industry, these definitions are specific to Red Hat Enterprise Linux (RHEL).

Update

Sometimes called a software patch, an update is an addition to the current version of the application, operating system, or software that you are running. A software update addresses any issues or bugs to provide a better experience of working with the technology. In RHEL, an update relates to a minor release, for example, updating from RHEL 8.1 to 8.2.

Upgrade

An upgrade is when you replace the application, operating system, or software that you are currently running with a newer version. Typically, you first back up your data according to instructions from Red Hat. When you upgrade RHEL, you have two options:

  • In-place upgrade: During an in-place upgrade, you replace the earlier version with the new version without removing the earlier version first. The installed applications and utilities, along with the configurations and preferences, are incorporated into the new version.
  • Clean install: A clean install removes all traces of the previously installed operating system, system data, configurations, and applications and installs the latest version of the operating system. A clean install is ideal if you do not need any of the previous data or applications on your systems or if you are developing a new project that does not rely on prior builds.

Operating system conversion

A conversion is when you convert your operating system from a different Linux distribution to Red Hat Enterprise Linux. Typically, you first back up your data according to instructions from Red Hat.

Migration

Typically, a migration indicates a change of platform: software or hardware. Moving from Windows to Linux is a migration. Moving a user from one laptop to another or a company from one server to another is a migration. However, most migrations also involve upgrades, and sometimes the terms are used interchangeably.

  • Migration to RHEL: Conversion of an existing operating system to RHEL
  • Migration across RHEL: Upgrade from one version of RHEL to another

Chapter 1. Supported upgrade paths
Copy link

The in-place upgrade replaces the RHEL 8 operating system on your system with a RHEL 9 version.

Important

It is not possible to perform an in-place upgrade directly from RHEL 7 to RHEL 9. However, you can perform an in-place upgrade from RHEL 7 to RHEL 8 and then perform a second in-place upgrade to RHEL 9.

Currently, it is possible to perform an in-place upgrade from the following source RHEL 8 minor versions to the following target RHEL 9 minor versions:

Expand
Table 1.1. Supported upgrade paths
System configurationSource OS versionTarget OS version

RHEL

RHEL 8.10

RHEL 9.4 (EUS)

RHEL 9.6 (EUS)

RHEL 9.7

RHEL with SAP HANA

RHEL 8.10

RHEL 9.4 (E4S)

RHEL 9.6 (E4S)

Important

In-place upgrade paths in this table are guaranteed only for systems that use Red Hat Subscription Manager (RHSM). For Pay-As-You-Go (PAYG) RHEL systems that use Red Hat Update Infrastructure (RHUI), only the latest available upgrade path is supported. Note that this does not impact RHEL systems with SAP HANA installed.

Chapter 2. Planning an upgrade to RHEL 9
Copy link

Before beginning your upgrade from RHEL 8 to RHEL 9, review system requirements, limitations, and other considerations.

2.1. Planning an upgrade from RHEL 8 to RHEL 9
Copy link

An in-place upgrade is the recommended and supported way to upgrade your system to the next major version of RHEL.

You should consider the following before upgrading to RHEL 9:

  • Operating system - The operating system is upgradable by the Leapp utility under the following conditions:

  • Applications - You can migrate applications installed on your system using Leapp. However, in certain cases, you have to create custom actors, which specify actions to be performed by Leapp during the upgrade, for example, reconfiguring an application or installing a specific hardware driver. For more information, see Handling the migration of your custom and third-party applications. Note that custom actors are unsupported by Red Hat.

    Important

    The SHA-1 algorithm has been deprecated in RHEL 9. If your system contains any packages with RSA/SHA-1 signatures, the upgrade is inhibited. Before upgrading, either remove these packages or contact the vendor for packages with RSA/SHA-256 signatures. For more information, see SHA-1 deprecation in Red Hat Enterprise Linux 9.

  • Security - You should evaluate this aspect before the upgrade and take additional steps when the upgrade process completes. Consider especially the following:

    • Before the upgrade, define the security standard your system has to comply with and understand the security changes in RHEL 9.
    • During the upgrade process, the Leapp utility sets SELinux mode to permissive.
    • Leapp supports in-place upgrades of RHEL 8.8 and later systems in Federal Information Processing Standard (FIPS) 140 mode to RHEL 9 FIPS-mode-enabled systems. FIPS mode stays enabled during the complete upgrade process.
    • After the upgrade is finished, re-evaluate and re-apply your security policies. For information about applying and updating security policies, see Applying security policies.

  • Storage and file systems

  • High Availability - If you are using the High Availability add-on, follow the Recommended Practices for Applying Software Updates to a RHEL High Availability or Resilient Storage Cluster Knowledgebase article.
  • Downtime - The upgrade process can take from several minutes to several hours.

  • Satellite

  • SAP HANA - If you are using SAP HANA, follow the Upgrading SAP environments from RHEL 8 to RHEL 9 guide instead. Note that the upgrade path for RHEL with SAP HANA might differ.
  • RHEL for Real Time - Upgrades on real-time systems are supported.
  • Real Time for Network Functions Virtualization (NFV) in Red Hat OpenStack Platform - Upgrades on real-time systems are supported.

  • Public clouds

    • Pay-As-You-Go - The in-place upgrade is supported for on-demand Pay-As-You-Go (PAYG) instances that use Red Hat Update Infrastructure (RHUI) on Amazon Web Services (AWS) on all supported architectures, and on Google Cloud and Microsoft Azure only on the Intel architecture.
    • Bring Your Own Service - The in-place upgrade is supported for Bring Your Own Subscription instances on all public clouds that use RHSM for a RHEL subscription.
  • Language - All Leapp reports, logs, and other generated documentation are in English, regardless of the language configuration.
  • Boot loader - It is not possible to switch the boot loader from BIOS to UEFI on RHEL 8 or RHEL 9. If your RHEL 8 system uses BIOS and you want your RHEL 9 system to use UEFI, perform a fresh install of RHEL 9 instead of an in-place upgrade. For more information, see Is it possible to switch the BIOS boot to UEFI boot on preinstalled Red Hat Enterprise Linux machine?

  • Known limitations - Notable known limitations of Leapp currently include:

See also Known Issues.

You can use Red Hat Lightspeed to determine which of the systems you have registered to Red Hat Lightspeed is on a supported upgrade path to RHEL 9. To do so, navigate to the respective Advisor recommendation in Red Hat Lightspeed, enable the recommendation under the Actions drop-down menu, and inspect the list under the Affected systems heading. Note that the Advisor recommendation considers only the RHEL 8 minor version and does not perform a pre-upgrade assessment of the system. See also Advisor-service recommendations overview.

Chapter 3. Preparing for the upgrade
Copy link

To prevent issues after the upgrade and to ensure that your system is ready to be upgraded to the next major version of RHEL, complete all necessary preparation steps before upgrading.

You must perform the preparation steps described in Preparing a RHEL 8 system for the upgrade on all systems. In addition, on systems that are registered to Satellite Server, you must also perform the preparation steps described in Preparing a Satellite-registered system for the upgrade.

3.1. Preparing a RHEL 8 system for the upgrade
Copy link

This procedure describes the steps that are necessary before performing an in-place upgrade to RHEL 9 by using the Leapp utility.

If you do not plan to use Red Hat Subscription Manager (RHSM) during the upgrade process, follow instructions in Upgrading to RHEL 9 without Red Hat Subscription Manager.

Prerequisites

  • The system meets conditions listed in Planning an upgrade.
  • If the system has been previously upgraded from RHEL 7 to RHEL 8, ensure that all required post-upgrade steps have been completed. For more information, see Performing post-upgrade tasks in the Upgrading from RHEL 7 to RHEL 8 guide.

Procedure

  1. Optional: Review the best practices in The best practices and recommendations for performing RHEL Upgrade using Leapp Knowledgebase article.
  2. Ensure your system has been successfully registered to the Red Hat Content Delivery Network (CDN) or Red Hat Satellite by using the Red Hat Subscription Manager.

  3. If you have registered your system to Satellite Server, complete the steps in Preparing a Satellite-registered system for the upgrade to ensure that your system meets the requirements for the upgrade.

    Important

    If your system is registered to Satellite Server, you must complete the steps in Preparing a Satellite-registered system for the upgrade for the upgrade before proceeding with the steps in this procedure to prevent issues from occurring.

  4. Optional: Unmount non-system OS file systems that are not required for the upgrade, such as file systems containing only data files unrelated to the system itself, and comment them out from the /etc/fstab file. This can reduce the amount of time needed for the upgrade process and prevent potential issues related to third-party applications that are not migrated properly during the upgrade by custom or third-party actors.

  5. Verify that the system is subscribed using subscription-manager:

    1. If your system is registered by using an account with Simple Content Access (SCA) enabled, verify that the Content Access Mode is set to Simple Content Access message appears: 

      # subscription-manager status
+-------------------------------------------+
   System Status Details
+-------------------------------------------+
Overall Status: Disabled
Content Access Mode is set to Simple Content Access. This host has access to content, regardless of subscription status.
System Purpose Status: Disabled
      Copy to Clipboard Toggle word wrap

    2. If your system is registered by using an account with SCA disabled, verify that the Red Hat Linux Server subscription is attached, the product name is Server, and the status is Subscribed. For example: 

      # subscription-manager list --installed
+-------------------------------------------+
    	  Installed Product Status
+-------------------------------------------+
Product Name:   Red Hat Enterprise Linux for x86_64
Product ID:     479
Version:        8.10
Arch:           x86_64
Status:         Subscribed
      Copy to Clipboard Toggle word wrap

  6. Ensure you have appropriate repositories enabled. The following command enables the Base and AppStream repositories for the 64-bit Intel architecture; for other architectures, see RHEL 8 repositories. 

    # subscription-manager repos --enable rhel-8-for-x86_64-baseos-rpms --enable rhel-8-for-x86_64-appstream-rpms
    Copy to Clipboard Toggle word wrap
    Note

    Optionally, you can enable the CodeReady Linux Builder (also known as Optional) or Supplementary repositories. For more information about repository IDs, see RHEL 8 repositories. For more information about the content of these repositories, see the Package manifest.

  7. Set the system release version:

    1. For systems subscribed using RHSM, lock the system to the source OS version: 

      # subscription-manager release --set 8.10
      Copy to Clipboard Toggle word wrap

    2. If you are upgrading by using Red Hat Update Infrastructure (RHUI) on a public cloud, set the expected system release version manually: 

      # rhui-set-release --set 8.10
      Copy to Clipboard Toggle word wrap
      Important

      If the rhui-set-release command is not available on your system, you can set the expected system release version by updating the /etc/dnf/vars/release file: 

      # echo "8.10" > /etc/dnf/vars/releasever
      Copy to Clipboard Toggle word wrap
  8. Optional: To use custom repositories, see the Configuring custom repositories Knowledgebase article.

  9. If you use the dnf versionlock plugin to lock packages to a specific version, clear the lock by running: 

    # dnf versionlock clear
    Copy to Clipboard Toggle word wrap

    For more information, see the Red Hat Knowledgebase solution How to restrict dnf to install or upgrade a package to a fixed specific package version?.

  10. If you performed an in-place upgrade from RHEL 7 to RHEL 8, ensure that there are no leftover upgrade-related files before you begin installing leapp-upgrade packages: 

    # rm -rf /usr/share/leapp-repository/repositories
    Copy to Clipboard Toggle word wrap

  11. If you are upgrading by using Red Hat Update Infrastructure (RHUI) on a public cloud, enable required RHUI repositories and install required RHUI packages to ensure your system is ready for upgrade:

    1. For AWS Red Hat Enterprise Linux: 

      # dnf config-manager --set-enabled rhui-client-config-server-8
# dnf -y install leapp-rhui-aws
      Copy to Clipboard Toggle word wrap

    2. For AWS Red Hat Enterprise Linux with High Availability: 

      # dnf config-manager --set-enabled rhui-client-config-server-8-ha
# dnf -y install leapp-rhui-aws-ha
      Copy to Clipboard Toggle word wrap

    3. For Microsoft Azure: 

      # dnf config-manager --set-enabled rhui-microsoft-azure-rhel8
# dnf -y install rhui-azure-rhel8 leapp-rhui-azure
      Copy to Clipboard Toggle word wrap
    4. For Google Cloud, follow the Leapp RHUI packages for Google Cloud Knowledgebase article.

  12. Install the Leapp utility: 

    # dnf install leapp-upgrade
    Copy to Clipboard Toggle word wrap

    Note that you need up-to-date leapp and leapp-repository packages, namely leapp version 0.19.0 of the leapp package and version 0.22.0 of the leapp-repository package.

    Note

    The leapp-repository package contains the leapp-upgrade-el8toel9 RPM package.

    Note

    If your system does not have internet access, download the following packages from the Red Hat Customer Portal:

    • leapp
    • leapp-deps
    • python3-leapp
    • leapp-upgrade-el8toel9
    • leapp-upgrade-el8toel9-deps

    • leapp-upgrade-el8toel9-fapolicyd

      • Include only if you installed the fapolicyd RPM package on your system.

  13. Update all packages to the latest RHEL 8 version and reboot: 

    # dnf update
# reboot
    Copy to Clipboard Toggle word wrap
  14. The latest release of the leapp-upgrade-el8toel9 package contains all required data files. If you have replaced these data files with older versions, remove all JSON files in the /etc/leapp/files directory and reinstall the leapp-upgrade-el8toel9 package to ensure your data files are up-to-date.
  15. Optional: Review, remediate, and then remove the rpmnew and rpmsave files. For more information, see What are rpmnew & rpmsave files?
  16. Temporarily disable antivirus software to prevent the upgrade from failing.

  17. Ensure that any configuration management system does not interfere with the in-place upgrade process:

    • If you use a configuration management system with a client-server architecture, such as Puppet, Salt, or Chef, disable the system before running the leapp preupgrade command. Do not enable the configuration management system until after the upgrade is complete to prevent issues during the upgrade.

    • If you use a configuration management system with agentless architecture, such as Ansible, do not execute the configuration and deployment file, such as an Ansible playbook, during the in-place upgrade as described in Performing the upgrade.

      Automation of the pre-upgrade and upgrade process by using a configuration management system is not supported by Red Hat. For more information, see Using configuration management systems to automate parts of the Leapp pre-upgrade and upgrade process on Red Hat Enterprise Linux.

  18. If your NSS database was created in RHEL 7 or earlier, verify that the database has been converted from the DBM database format to SQLite. For more information, see Updating NSS databases from DBM to SQLite.
  19. RHEL 9 does not support the legacy network-scripts package, which was deprecated in RHEL 8. Before upgrading, move your custom network scripts and write a NetworkManager dispatcher script that executes your existing custom scripts. For more information, see the Red Hat Knowledgebase solution Migrating custom network scripts to NetworkManager dispatcher scripts.
  20. If you are upgrading using an ISO image, verify that the ISO image contains the target OS version, for example, RHEL 9.6, and is saved to a persistent local mount point to ensure that the Leapp utility can access the image throughout the upgrade process.

  21. Ensure that you have a full system backup or a virtual machine snapshot. You should be able to get your system to the pre-upgrade state if you follow standard disaster recovery procedures within your environment. You can use the following backup options:

This procedure describes the steps that are necessary to prepare a system that is registered to Satellite for the upgrade to RHEL 9. There steps are performed on the Satellite Server.

Important

Users on Satellite systems must complete the preparatory steps described both in this procedure and in Preparing a RHEL 8 system for the upgrade.

Prerequisites

  • You have administrative privileges for the Satellite Server.

Procedure

  1. Verify that Satellite is on a version in full or maintenance support. For more information, see Red Hat Satellite Product Life Cycle.
  2. Import a subscription manifest with RHEL 9 repositories into Satellite Server. For more information, see the Managing Red Hat Subscriptions chapter in the Managing Content Guide for the particular version of Red Hat Satellite, for example, for version 6.17.

  3. Enable and synchronize all required RHEL 8 and RHEL 9 repositories on the Satellite Server with the latest updates for the source and target OS versions. Required repositories must be available in the Content View and enabled in the associated activation key.

    Note

    For RHEL 9 repositories, enable the target OS version, for example, RHEL 9.6, of each repository. If you enable only the RHEL 9 version of the repositories, the in-place upgrade is inhibited.

    For example, for the Intel architecture without an Extended Update Support (EUS) subscription, enable at minimum the following repositories:

    • Red Hat Enterprise Linux 8 for x86_64 - AppStream (RPMs)

      rhel-8-for-x86_64-appstream-rpms

      x86_64 <source_os_version>

    • Red Hat Enterprise Linux 8 for x86_64 - BaseOS (RPMs)

      rhel-8-for-x86_64-baseos-rpms

      x86_64 <source_os_version>

    • Red Hat Enterprise Linux 9 for x86_64 - AppStream (RPMs)

      rhel-9-for-x86_64-appstream-rpms

      x86_64 <target_os_version>

    • Red Hat Enterprise Linux 9 for x86_64 - BaseOS (RPMs)

      rhel-9-for-x86_64-baseos-rpms

      x86_64 <target_os_version>

      Replace <source_os_version> and <target_os_version> with the source OS version and target OS version respectively, for example, 8.10 and 9.6.

      For other architectures, see RHEL 8 repositories and RHEL 9 repositories.

      For more information, see the Importing Content chapter in the Managing Content Guide for the particular version of Red Hat Satellite, for example, for version 6.17.

  4. Attach the content host to a Content View containing the required RHEL 8 and RHEL 9 repositories.

    For more information, see the Managing Content Views chapter in the Managing Content Guide for the particular version of Red Hat Satellite, for example, for version 6.17.

Verification

  1. Verify that the correct RHEL 8 and RHEL 9 repositories have been added to the correct Content View on Satellite Server.

    1. In the Satellite web UI, navigate to Content > Lifecycle > Content Views and click the name of the Content View.

    2. Click the Repositories tab and verify that the repositories appear as expected.

      Note

      You can also verify that the repositories have been added to the Content View using the following commands: 

      # hammer repository list --search 'content_label ~ rhel-8' --content-view <content_view_name> --organization <organization> --lifecycle-environment <lifecycle_environment>
# hammer repository list --search 'content_label ~ rhel-9' --content-view <content_view_name> --organization <organization> --lifecycle-environment <lifecycle_environment>
      Copy to Clipboard Toggle word wrap

      Replace <content_view_name> with the name of the Content View, <organization> with the organization, and <lifecycle_environement> with the name of the lifecycle environment..

  2. Verify that the correct RHEL 9 repositories are enabled in the activation key associated with the Content View:

    1. In Satellite web UI navigate to Content > Lifecycle > Activation Keys and click the name of the activation key.
    2. Click the Repository Sets tab and verify that the statuses of the required repositories are Enabled.

  3. . Verify that all expected RHEL 8 repositories are enabled in the host. For example: 

    # subscription-manager repos --list-enabled | grep "^Repo ID"
Repo ID:   rhel-8-for-x86_64-baseos-rpms
Repo ID:   rhel-8-for-x86_64-appstream-rpms
    Copy to Clipboard Toggle word wrap

3.3. Configuring the upgrade with LiveMode
Copy link

LiveMode is an alternative method of preparing and booting to the upgrade environment when upgrading from RHEL 8 to RHEL 9 on the 64-bit Intel architecture. LiveMode uses the standard booting process. The standard booting process can prevent or help diagnose certain problems that occur during the upgrade, such as issues related to the storage initialization. Note that LiveMode requires approximately 700 MB of additional disk space to create and store the upgrade environment before the reboot.

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.

When using LiveMode, you can also configure the upgrade experience beyond the default specifications. This can be useful when troubleshooting during the upgrade process or if you want to view the upgrade’s progress by using an SSH connection.

If you are using LiveMode without any modifications to the default settings, you do not need to complete any preparation steps for LiveMode before the upgrade. If you want to change the default specifications, you must create and modify a YAML file.

Procedure

  1. If you want to modify LiveMode’s default specifications, create a YAML file in the /etc/leapp/actor_conf.d/ file, for example livemode.yaml.

  2. Enter the desired LiveMode configuration into the YAML file.

    Expand
    Table 3.1. LiveMode configuration
    Configuration fieldValue typeDefaultDescription

    additional_packages

    List[str]

    []

    Additional packages to be installed into the upgrade image.

    autostart_upgrade_after_reboot

    bool

    True

    If set to True, the upgrade starts automatically after the reboot. Otherwise, a manual trigger is required.

    capture_strace_info_into

    str

    ''

    If set to a non-empty string, leapp is executed under strace and results are stored within the provided file path.

    dracut_network

    str

    ''

    Dracut network arguments. Required if the `url_to_load_squashfs_`from option is set to a non-empty string.

    setup_network_manager

    bool

    False

    If set to False, the Leapp tool enables Network Manager in the upgrade image.

    setup_opensshd_using_auth_keys

    str

    ''

    If set to a non-empty string, openssh daemon is set up within the upgrade image using the provided authorized keys file.

    setup_passwordless_root

    bool

    False

    If set to True, the root account of the upgrade image has an empty password. Use with caution.

    squashfs_image_path

    str

    /var/lib/leapp/live-upgrade.img

    Desired location of the upgrade image of the minimal target system.

    url_to_load_squashfs_image_from

    str

    ''

    URL of the desired upgrade image.

    The following is an example of a /etc/leapp/actor_conf.d/livemode.yaml file: 

    livemode:
  additional_packages : [ vim ]
  autostart_upgrade_after_reboot : false
  setup_network_manager : true
  setup_opensshd_using_auth_keys : /root/.ssh/authorized_keys
    Copy to Clipboard Toggle word wrap

    The example file results in the following actions:

    • The Leapp utility installs the vim package into the upgrade environment.
    • The upgrade does not start automatically after reboot. You must manually restart it. This allows you to manually inspect the system and verify that the upgrade finished as expected and the system is ready for use before starting.
    • The Leapp utility attempts to enable NetworkManager inside the upgrade environment by using the source system’s network profiles.
    • The Leapp utility enables the opensshd service. If the system establishes network access successfully, you can use SSH to log in to the upgrade environment by using the root account and interact with the system.

Chapter 4. Reviewing the pre-upgrade report
Copy link

To assess upgradability of your system, start the pre-upgrade process by using the leapp preupgrade command. During this phase, the Leapp utility collects data about the system, assesses upgradability, and generates a pre-upgrade report. The pre-upgrade report summarizes potential problems and suggests recommended solutions. The report also helps you decide whether it is possible or advisable to proceed with the upgrade.

Note

The pre-upgrade assessment does not modify the system configuration, but it does consume non-negligible space in the /var/lib/leapp directory. In most cases, the pre-upgrade assessment requires up to 4 GB of space, but the actual size depends on your system configuration. If there is not enough space in the hosted file system, the pre-upgrade report might not show complete results of the analysis. To prevent issues, ensure that your system has enough space in the /var/lib/leapp directory or move the directory to a dedicated partition so that space consumption does not affect other parts of the system.

Important

Always review the entire pre-upgrade report, even when the report finds no inhibitors to the upgrade. The pre-upgrade report contains recommended actions to complete before the upgrade to ensure that the upgraded system functions correctly.

Reviewing a pre-upgrade report can also be useful if you want to perform a fresh installation of a RHEL 9 system instead of the in-place upgrade process.

You can assess upgradability in the pre-upgrade phase using either of the following ways:

  • Review the pre-upgrade report in the generated leapp-report.txt file and manually resolve reported problems using the command line.
  • Use the web console to review the report, apply automated remediations where available, and fix remaining problems using the suggested remediation hints.
Note

You can process the pre-upgrade report by using your own custom scripts, for example, to compare results from multiple reports across different environments. For more information, see Automating your Red Hat Enterprise Linux pre-upgrade report workflow.

Important

The pre-upgrade report cannot simulate the entire in-place upgrade process and therefore cannot identify all inhibiting problems with your system. As a result, your in-place upgrade might still be terminated even after you have reviewed and remediated all problems in the report. For example, the pre-upgrade report cannot detect issues related to broken package downloads.

Identify potential upgrade problems during the pre-upgrade phase before the upgrade by using the command line.

Prerequisites

  • The steps listed in Preparing for the upgrade have been completed.

  • You are logged in to root with the unconfined SELinux role. If you are using sudo, you must use the -r unconfined_r -t unconfined_t options when running each leapp command, for example: 

    $ sudo -r unconfined_r -t unconfined_t leapp preupgrade
    Copy to Clipboard Toggle word wrap

Procedure

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

    # leapp preupgrade --target <_target_os_version_>
    Copy to Clipboard Toggle word wrap

    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> ...
      Copy to Clipboard Toggle word wrap
    • 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
      Copy to Clipboard Toggle word wrap

      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>
      Copy to Clipboard Toggle word wrap

      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
      Copy to Clipboard Toggle word wrap
  4. Repeat the previous steps to rerun the pre-upgrade report to verify that you have resolved all critical issues.

Identify potential problems in the pre-upgrade phase before the upgrade and apply automated remediations by using the web console.

Prerequisites

  • You have completed the steps listed in Preparing for the upgrade.

  • You are logged in to root with the unconfined SELinux role. If you are using sudo, you must use the -r unconfined_r -t unconfined_t options when running each leapp command, for example: 

    $ sudo -r unconfined_r -t unconfined_t leapp preupgrade
    Copy to Clipboard Toggle word wrap

Procedure

  1. Install the cockpit-leapp plug-in: 

    # dnf install cockpit-leapp
    Copy to Clipboard Toggle word wrap
  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 <target_os_version>
    Copy to Clipboard Toggle word wrap

    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> ...
      Copy to Clipboard Toggle word wrap
    • 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
      Copy to Clipboard Toggle word wrap

      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

    In-place upgrade report in the web console
    View larger image
    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>
      Copy to Clipboard Toggle word wrap

      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
      Copy to Clipboard Toggle word wrap
      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

      Detail pane
      View larger image
      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.

Chapter 5. Performing the upgrade
Copy link

After you have completed the preparatory steps and reviewed and resolved the problems found in the pre-upgrade report, you can perform the in-place upgrade on your system.

5.1. Performing the upgrade from RHEL 8 to RHEL 9
Copy link

This procedure lists steps required to perform the upgrade by using the Leapp utility.

Prerequisites

Procedure

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

    # leapp upgrade --target <_target_os_version_>
    Copy to Clipboard Toggle word wrap

    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> ...
      Copy to Clipboard Toggle word wrap
    • 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
      Copy to Clipboard Toggle word wrap

      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
      Copy to Clipboard Toggle word wrap

      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
    Copy to Clipboard Toggle word wrap

    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.

Chapter 6. Verifying the post-upgrade state
Copy link

After performing the in-place upgrade to RHEL 9, verify that the system is in the correct state. Doing so allows you to identify and correct any critical errors that could impact your system.

This procedure lists Verification recommended to perform after an in-place upgrade to RHEL 9.

Prerequisites

  • The system has been upgraded following the steps described in Performing the upgrade and you have been able to log in to RHEL 9.

Procedure

After the upgrade completes, determine whether the system is in the required state, at least:

  • Verify that the Leapp utility has finished all actions in the upgrade process and the system is ready to be used: 

    # [ -e "/etc/systemd/system/leapp_resume.service" ] || ps -e | grep -q leapp && echo "Leapp has not finished the execution yet!"
    Copy to Clipboard Toggle word wrap
    Important

    If you attempt to use the system before the upgrade is complete, serious issues could occur.

  • Verify that the current OS version is RHEL 9. For example: 

    # cat /etc/redhat-release
Red Hat Enterprise Linux release 9.6 (Plow)
    Copy to Clipboard Toggle word wrap

  • Check the OS kernel version. For example: 

    # uname -r
5.14.0-70.10.1.el9_0.x86_64
    Copy to Clipboard Toggle word wrap

    Note that .el9 is important and the version should not be earlier than 5.14.0.

  • If you are using the Red Hat Subscription Manager:

    • Verify that the correct product is installed. For example: 

      # subscription-manager list --installed
+-----------------------------------------+
    	  Installed Product Status
+-----------------------------------------+
Product Name: Red Hat Enterprise Linux for x86_64
Product ID:   479
Version:      9.6
Arch:         x86_64
Status:       Subscribed
      Copy to Clipboard Toggle word wrap

    • Verify that the release version is set to the expected target OS version immediately after the upgrade. For example: 

      # subscription-manager release
Release: 9.6
      Copy to Clipboard Toggle word wrap
  • Verify that network services are operational, for example, try to connect to a server using SSH.
  • Check the post-upgrade status of your applications. In some cases, you may need to perform migration and configuration changes manually. For example, to migrate your databases, follow instructions in Configuring and using database servers.

After the in-place upgrade, clean up your RHEL 9 system by remove unneeded packages, disable incompatible repositories, and update the rescue kernel and initial RAM disk.

7.1. Performing post-upgrade tasks
Copy link

This procedure lists major tasks recommended to perform after an in-place upgrade to RHEL 9.

Prerequisites

and you have been able to log in to RHEL 9.

  • The status of the in-place upgrade has been verified following the steps described in Verifying the post-upgrade state. This includes verification that the Leapp utility has finished the upgrade process.

Procedure

After performing the upgrade, complete the following tasks:

  1. Remove any remaining Leapp packages from the exclude list in the /etc/dnf/dnf.conf configuration file, including the snactor package, which is a tool for upgrade extension development. During the in-place upgrade, Leapp packages that were installed with the Leapp utility are automatically added to the exclude list to prevent critical files from being removed or updated. After the in-place upgrade, these Leapp packages must be removed from the exclude list before they can be removed from the system.

    • To manually remove packages from the exclude list, edit the /etc/dnf/dnf.conf configuration file and remove the desired Leapp packages from the exclude list.

    • To remove all packages from the exclude list: 

      # dnf config-manager --save --setopt exclude=''
      Copy to Clipboard Toggle word wrap

  2. Remove remaining RHEL 8 packages, including remaining Leapp packages.

    1. Remove the old kernel packages from the RHEL 9 system. For more information on removing kernel packages, see the Red Hat Knowledgebase solution What is the proper method to remove old kernels from a Red Hat Enterprise Linux system?

    2. Locate remaining RHEL 8 packages: 

      # rpm -qa | grep -e '\.el[78]' | grep -vE '^(gpg-pubkey|libmodulemd|katello-ca-consumer)' | sort
      Copy to Clipboard Toggle word wrap

    3. Remove remaining RHEL 8 packages from your RHEL 9 system. To ensure that RPM dependencies are maintained, use the dnf remove command.

      For example: 

      # dnf remove $(rpm -qa | grep \.el[78] | grep -vE 'gpg-pubkey|libmodulemd|katello-ca-consumer')
      Copy to Clipboard Toggle word wrap
      Important

      This step might also remove third-party packages. Review the transaction before accepting to ensure no packages are unintentionally removed.

    4. Remove remaining Leapp dependency packages: 

      # dnf remove leapp-deps-el9 leapp-repository-deps-el9
      Copy to Clipboard Toggle word wrap

  3. Optional: Remove all remaining upgrade-related data from the system: 

    # rm -rf /var/log/leapp /root/tmp_leapp_py3 /var/lib/leapp
    Copy to Clipboard Toggle word wrap
    Important

    Removing this data might limit Red Hat Support’s ability to investigate and troubleshoot post-upgrade problems.

  4. Disable DNF repositories whose packages are not RHEL 9-compatible. Repositories managed by RHSM are handled automatically. To disable these repositories: 

    # dnf config-manager --set-disabled <repository_id>
    Copy to Clipboard Toggle word wrap

    Replace repository_id with the repository ID.

  5. Replace the old rescue kernel and initial RAM disk with the current kernel and disk:

    1. Remove the existing rescue kernel and initial RAM disk: 

      # rm /boot/vmlinuz-*rescue* /boot/initramfs-*rescue*
      Copy to Clipboard Toggle word wrap

    2. Reinstall the rescue kernel and related initial RAM disk: 

      # /usr/lib/kernel/install.d/51-dracut-rescue.install add "$(uname -r)" /boot "/boot/vmlinuz-$(uname -r)"
      Copy to Clipboard Toggle word wrap

    3. If your system is on the IBM Z architecture, update the zipl boot loader: 

      # zipl
      Copy to Clipboard Toggle word wrap

  6. Check existing configuration files:

    • Review, remediate, and then remove the rpmnew, rpmsave, and leappsave files. Note that rpmsave and leappsave are equivalent and can be handled similarly. For more information, see What are rpmnew & rpmsave files?
    • Remove configuration files for RHEL 8 DNF modules from the /etc/dnf/modules.d/ directory that are no longer valid. Note that these files have no effect on the system when related DNF modules do not exist.
  7. Re-evaluate and re-apply your security policies. Especially, change the SELinux mode to enforcing. For details, see Applying security policies.

Verification

  1. Verify that the previously removed rescue kernel and rescue initial RAM disk files have been created for the current kernel: 

    # ls /boot/vmlinuz-*rescue* /boot/initramfs-*rescue* 
# lsinitrd /boot/initramfs-*rescue*.img | grep -qm1 "$(uname -r)/kernel/" && echo "OK" || echo "FAIL"
    Copy to Clipboard Toggle word wrap

  2. Verify the rescue boot entry refers to the existing rescue files. See the grubby output: 

    # grubby --info /boot/vmlinuz-*rescue*
    Copy to Clipboard Toggle word wrap

  3. Review the grubby output and verify that no RHEL 8 boot entries are configured: 

    # grubby --info ALL
    Copy to Clipboard Toggle word wrap

  4. Verify that no files related to previous RHEL are present in the /boot/loader/entries file: 

    # grep -r ".el8" "/boot/loader/entries/" || echo "Everything seems ok."
    Copy to Clipboard Toggle word wrap

Chapter 8. Applying security policies
Copy link

During the in-place upgrade process, the SELinux policy must be switched to permissive mode. Furthermore, security profiles might contain changes between major releases. To restore system security, switch SELinux to enforcing mode again and verify the system-wide cryptographic policy. You may also want to remediate the system to be compliant with a specific security profile. Also, some security-related components require pre-update steps for a correct upgrade.

8.1. Changing SELinux mode to enforcing
Copy link

During the in-place upgrade process, the Leapp utility sets SELinux mode to permissive. When the system is successfully upgraded, you have to manually change SELinux mode to enforcing.

Prerequisites

Procedure

  1. Ensure that there are no SELinux denials, for example, by using the ausearch utility: 

    # ausearch -m AVC,USER_AVC -ts boot
    Copy to Clipboard Toggle word wrap

    Note that the previous step covers only the most common scenario. To check for all possible SELinux denials, see the Identifying SELinux denials section in the Using SELinux title, which provides a complete procedure.

  2. Open the /etc/selinux/config file in a text editor of your choice, for example: 

    # vi /etc/selinux/config
    Copy to Clipboard Toggle word wrap

  3. Configure the SELINUX=enforcing option: 

    # This file controls the state of SELinux on the system.
# SELINUX= can take one of these three values:
#       enforcing - SELinux security policy is enforced.
#       permissive - SELinux prints warnings instead of enforcing.
#       disabled - No SELinux policy is loaded.
SELINUX=enforcing
# SELINUXTYPE= can take one of these two values:
#       targeted - Targeted processes are protected,
#       mls - Multi Level Security protection.
SELINUXTYPE=targeted
    Copy to Clipboard Toggle word wrap

  4. Save the change, and restart the system: 

    # reboot
    Copy to Clipboard Toggle word wrap

Verification

  1. After the system restarts, confirm that the getenforce command returns Enforcing: 

    $ getenforce
Enforcing
    Copy to Clipboard Toggle word wrap

8.2. System-wide cryptographic policies
Copy link

The system-wide cryptographic policies is a system component that configures the core cryptographic subsystems, covering the TLS, IPSec, SSH, DNSSec, and Kerberos protocols.

The in-place upgrade process preserves the cryptographic policy you used in RHEL 8. For example, if you used the DEFAULT cryptographic policy in RHEL 8, your system upgraded to RHEL 9 also uses DEFAULT. Note that specific settings in predefined policies differ, and RHEL 9 cryptographic policies contain more strict and more secure default values. For example, the RHEL 9 DEFAULT cryptographic policy restricts SHA-1 usage for signatures and the LEGACY policy no longer allows DH and RSA ciphers with less than 2048 bits. See the Using system-wide cryptographic policies section in the Security hardening document for more information. Custom cryptographic policies are preserved across the in-place upgrade.

To view or change the current system-wide cryptographic policy, use the update-crypto-policies tool: 

$ update-crypto-policies --show
DEFAULT
Copy to Clipboard Toggle word wrap

For example, the following command switches the system-wide crypto policy level to FUTURE, which should withstand any near-term future attacks: 

# update-crypto-policies --set FUTURE
Setting system policy to FUTURE
Copy to Clipboard Toggle word wrap

If your scenario requires the use of SHA-1 for verifying existing or third-party cryptographic signatures, you can enable it by entering the following command: 

# update-crypto-policies --set DEFAULT:SHA1
Copy to Clipboard Toggle word wrap

Alternatively, you can switch the system-wide crypto policies to the LEGACY policy. However, LEGACY also enables many other algorithms that are not secure.

Warning

Enabling the SHA subpolicy makes your system more vulnerable than the default RHEL 9 settings. Switching to the LEGACY policy is even less secure, and you should use it with caution.

You can also customize system-wide cryptographic policies. For details, see the Customizing system-wide cryptographic policies with subpolicies and Creating and setting a custom system-wide cryptographic policy sections. If you use a custom cryptographic policy, consider reviewing and updating the policy to mitigate threats brought by advances in cryptography and computer hardware.

To get a fully hardened system after a successful upgrade to RHEL 9, you can use automated remediation provided by the OpenSCAP suite. OpenSCAP remediations align your system with security baselines, such as PCI-DSS, OSPP, or ACSC Essential Eight. The configuration compliance recommendations differ among major versions of RHEL due to the evolution of the security offering.

When upgrading a hardened RHEL 8 system, the Leapp tool does not provide direct means to retain the full hardening. Depending on the changes in the component configuration, the system might diverge from the recommendations for the RHEL 9 during the upgrade.

Note

You cannot use the same SCAP content for scanning RHEL 8 and RHEL 9. Update the management platforms if the compliance of the system is managed by tools such as Red Hat Satellite or Red Hat Lightspeed.

As an alternative to automated remediations, you can make the changes manually by following an OpenSCAP-generated report. For information about generating a compliance report, see Scanning the system for security compliance and vulnerabilities.

Important

Automated remediations support RHEL systems in the default configuration. Because the system configuration has been altered after the upgrade, running automated remediations might not make the system fully compliant with the required security profile. You might need to fix some requirements manually.

The following example procedure hardens your system settings according to the PCI-DSS profile.

Prerequisites

  • The scap-security-guide package is installed on your RHEL 9 system.

Procedure

  1. Find the appropriate security compliance data stream .xml file: 

    $ ls /usr/share/xml/scap/ssg/content/
...
ssg-rhel9-ds.xml
...
    Copy to Clipboard Toggle word wrap

    See the Viewing compliance profiles section for more information.

  2. Remediate the system according to the selected profile from the appropriate data stream: 

    # oscap xccdf eval --profile pci-dss --remediate /usr/share/xml/scap/ssg/content/ssg-rhel9-ds.xml
    Copy to Clipboard Toggle word wrap

    You can replace the pci-dss value in the --profile argument with the ID of the profile according to which you want to harden your system. For a full list of profiles supported in RHEL 9, see SCAP security profiles supported in RHEL.

    Warning

    If not used carefully, running the system evaluation with the --remediate option enabled might render the system non-functional. Red Hat does not provide any automated method to revert changes made by security-hardening remediations. Remediations are supported on RHEL systems in the default configuration. If your system has been altered after the installation, running remediation might not make it compliant with the required security profile.

  3. Restart your system: 

    # reboot
    Copy to Clipboard Toggle word wrap

Verification

  1. Verify that the system is compliant with the profile, and save the results in an HTML file: 

    $ oscap xccdf eval --report pcidss_report.html --profile pci-dss /usr/share/xml/scap/ssg/content/ssg-rhel9-ds.xml
    Copy to Clipboard Toggle word wrap

8.4. Verifying USBGuard policies
Copy link

With the USBGuard software framework, you can protect your systems against intrusive USB devices by using lists of permitted and forbidden devices based on the USB device authorization feature in the kernel.

Prerequisites

  • You have created a rule set for USB devices that reflected the requirements of your scenario before the upgrade.
  • The usbguard service is installed and running on your RHEL 9 system.

Procedure

  1. Back up your *.conf files stored in the /etc/usbguard/ directory.
  2. Use the usbguard generate-policy to generate a new policy file. Note that the command generates rules for the currently present USB devices only.

  3. Compare the newly generated rules against the rules in the previous policy:

    1. If you identify differences in the rules for the devices that were present when you generated the new policy and the pre-upgrade rules for the same devices, modify the original rules correspondingly also for devices that might be inserted later.
    2. If there are no differences between the newly generated and the pre-upgrade rules, you can use the policy files created in RHEL 8 without any modification.

8.5. Updating fapolicyd databases
Copy link

The fapolicyd software framework controls the execution of applications based on a user-defined policy.

In rare cases, a problem with the fapolicyd trust database format can occur. To rebuild the database:

  1. Stop the service: 

    # systemctl stop fapolicyd
    Copy to Clipboard Toggle word wrap

  2. Delete the database: 

    # fapolicyd-cli --delete-db
    Copy to Clipboard Toggle word wrap

  3. Start the service: 

    # systemctl start fapolicyd
    Copy to Clipboard Toggle word wrap

If you added custom trust files to the trust database, update them either individually by using the fapolicyd-cli -f update <FILE> command or altogether by using fapolicyd-cli -f update. To apply the changes, use either the fapolicyd-cli --update command or restart the fapolicyd service.

Additionally, custom binaries might require a rebuild for the new RHEL version. Perform any such updates before you update the fapolicyd database.

8.6. Updating NSS databases from DBM to SQLite
Copy link

Many applications automatically convert the NSS database format from DBM to SQLite after you set the NSS_DEFAULT_DB_TYPE environment variable to the sql value on the system. You can ensure that all databases are converted by using the certutil tool.

Note

Convert your NSS databases stored in the DBM format before you upgrade to RHEL 9. In other words, perform the following steps on RHEL systems (6, 7, and 8) from which you want to upgrade to RHEL 9.

Prerequisites

  • The nss-tools package is installed on your system.

Procedure

  1. Set NSS_DEFAULT_DB_TYPE to sql on the system: 

    # export NSS_DEFAULT_DB_TYPE=sql
    Copy to Clipboard Toggle word wrap

  2. Use the conversion command in every directory[1] that contains NSS database files in the DBM format, for example: 

    # certutil -K -X -d /etc/ipsec.d/
    Copy to Clipboard Toggle word wrap

    Note that you have to provide a password or a path to a password file as a value of the -f option if your database file is password-protected, for example: 

    # certutil -K -X -f /etc/ipsec.d/nsspassword -d /etc/ipsec.d/
    Copy to Clipboard Toggle word wrap

[1] RHEL contains a system-wide NSS database in the /etc/pki/nssdb directory. Other locations depend on applications you use. For example, Libreswan stores its database in the /etc/ipsec.d/ directory and Firefox uses the /home/<username>/.mozilla/firefox/ directory.

The RHEL 9 cyrus-sasl package is built without the libdb dependency, and the sasldb plugin uses the GDBM database format instead of Berkeley DB.

Prerequisites

  • The cyrus-sasl-lib package is installed on your system.

Procedure

  • To migrate your existing Simple Authentication and Security Layer (SASL) databases stored in the old Berkeley DB format, use the cyrusbdb2current tool with the following syntax: 

    # cyrusbdb2current <sasldb_path> <new_path>
    Copy to Clipboard Toggle word wrap

Chapter 9. Troubleshooting
Copy link

You can refer to the following tips to troubleshoot upgrading from RHEL 8 to RHEL 9.

9.1. Troubleshooting resources
Copy link

You can refer to the following troubleshooting resources.

Console output

By default, only error and critical log level messages are printed to the console output by the Leapp utility. To change the log level, use the --verbose or --debug options with the leapp upgrade command.

  • In verbose mode, Leapp prints info, warning, error, and critical messages.
  • In debug mode, Leapp prints debug, info, warning, error, and critical messages.

Logs

  • The /var/log/leapp/leapp-upgrade.log file lists issues found during the initramfs phase.
  • The /var/log/leapp/dnf-debugdata/ directory contains transaction debug data. This directory is present only if the leapp upgrade command is executed with the --debug option.
  • The /var/log/leapp/answerfile contains questions required to be answered by Leapp.
  • The journalctl utility provides complete logs.

Reports

9.2. Troubleshooting tips
Copy link

You can refer to the following troubleshooting tips.

Pre-upgrade phase

  • Verify that your system meets all conditions listed in Planning an upgrade.
  • Make sure you have followed all steps described in Preparing for the upgrade for example, your system does not use more than one Network Interface Card (NIC) with a name based on the prefix used by the kernel (eth).

  • Make sure you have answered all questions required by Leapp in the /var/log/leapp/answerfile file. If any answers are missing, Leapp inhibits the upgrade. For example:

    • Are there no VDO devices on the system?
  • Make sure you have resolved all problems identified in the pre-upgrade report, located at /var/log/leapp/leapp-report.txt. To achieve this, you can also use the web console, as described in Assessing upgradability and applying automated remediations through the web console.

Example 9.1. Leapp answerfile

The following is an example of an unedited /var/log/leapp/answerfile file that has one unanswered question: 

[check_vdo]
# Title:              None
# Reason:             Confirmation
# ============================= check_vdo.confirm =============================
# Label:              Are all VDO devices, if any, successfully converted to LVM management?
# Description:        Enter True if no VDO devices are present on the system or all VDO devices on the system have been successfully converted to LVM management. Entering True will circumvent check of failures and undetermined devices. Recognized VDO devices that have not been converted to LVM management can still block the upgrade despite the answer.All VDO devices must be converted to LVM management before upgrading.
# Reason:             To maximize safety all block devices on a system that meet the criteria as possible VDO devices are checked to verify that, if VDOs, they have been converted to LVM management. If the devices are not converted and the upgrade proceeds the data on unconverted VDO devices will be inaccessible. In order to perform checking the 'vdo' package must be installed. If the 'vdo' package is not installed and there are any doubts the 'vdo' package should be installed and the upgrade process re-run to check for unconverted VDO devices. If the check of any device fails for any reason an upgrade inhibiting report is generated. This may be problematic if devices are dynamically removed from the system subsequent to having been identified during device discovery. If it is certain that all VDO devices have been successfully converted to LVM management this dialog may be answered in the affirmative which will circumvent block device checking.
# Type:               bool
# Default:            None
# Available choices: True/False
# Unanswered question. Uncomment the following line with your answer
# confirm =
Copy to Clipboard Toggle word wrap

The Label field specifies the question that requires an answer. In this example, the question is Are all VDO devices, if any, successfully converted to LVM management?

To answer the question, uncomment the last line and enter an answer of True or False. In this example, the selected answer is True: 

[check_vdo]
...
# Available choices: True/False
# Unanswered question. Uncomment the following line with your answer
confirm = True
Copy to Clipboard Toggle word wrap

Download phase

  • If a problem occurs during downloading RPM packages, examine transaction debug data located in the /var/log/leapp/dnf-debugdata/ directory.

    Note

    The /var/log/leapp/dnf-debugdata/ directory is empty or does not exist if no transaction debug data was produced. This might occur when the required repositories are not available.

Initramfs phase

  • During this phase, potential failures redirect you to the Dracut shell. Check the Journal log: 

    # journalctl
    Copy to Clipboard Toggle word wrap

    Alternatively, restart the system from the Dracut shell using the reboot command and check the /var/log/leapp/leapp-upgrade.log file.

Post-upgrade phase

  • If your system seems to be successfully upgraded but booted with the old RHEL 8 kernel, restart the system and check the kernel version of the default entry in GRUB.
  • Make sure you have followed the recommended steps in Verifying the post-upgrade state.

  • If your application or a service stops working or behaves incorrectly after you have switched SELinux to enforcing mode, search for denials using the ausearch, journalctl, or dmesg utilities: 

    # ausearch -m AVC,USER_AVC -ts boot
# journalctl -t setroubleshoot
# dmesg | grep -i -e selinux -e type=1400
    Copy to Clipboard Toggle word wrap

    The most common problems are caused by incorrect labeling. See Troubleshooting problems related to SELinux for more details.

9.3. Known issues for the RHEL 8 to RHEL 9 upgrade
Copy link

The following are Known Issues you may encounter when upgrading.

  • Network teaming currently does not work when the in-place upgrade is performed while Network Manager is disabled or not installed.
  • If your RHEL 8 system uses a device driver that is provided by Red Hat but is not available in RHEL 9, Leapp inhibits the upgrade. However, if the RHEL 8 system uses a third-party device driver that Leapp does not have data for in the /etc/leapp/files/device_driver_deprecation_data.json file, Leapp does not detect such a driver and proceeds with the upgrade. Consequently, the system might fail to boot after the upgrade.

  • If the name of a third-party package (not signed by Red Hat) installed on your system is the same as the name of a package provided by Red Hat, the in-place upgrade fails. To work around this problem, choose one of the following options prior to upgrading:

    1. Remove the third-party package
    2. Replace the third-party package with the package provided by Red Hat
  • In RHEL 8, you can manage Virtual Data Optimizer (VDO) volumes by using either the VDO manager or the Logical Volume Manager (LVM). In RHEL 9, it is only possible to manage VDO volumes by using LVM. To continue using VDO-managed volumes on RHEL 9, import those volumes to LVM-managed VDO volumes before the upgrade. For more information, see Importing existing VDO volumes to LVM.
  • The in-place upgrade might fail on systems with Software Redundant Array of Independent Disks (RAID). (BZ#1957192)

  • If any of the mounted file systems that are defined in the /etc/fstab file do not have the shared propagation flag set, the upgrade might fail. To prevent this issue, remount these file systems to set them as shared: 

    # mount -o remount --make-shared <mountpoint>
    Copy to Clipboard Toggle word wrap

    Replace mountpoint with the mountpoint of each file system.

    For more information, see the Red Hat Knowledgebase solution Leapp "Can not load RPM file" during the DNF transaction check. (RHEL-23449)

  • If you are upgrading by using RHUI, files in the /usr/share/leapp-repository/repositories/system_upgrade/common/files/rhui/ directory are incorrectly reported as custom files in the pre-upgrade report. Unless you modified these files manually, you can ignore the warnings about these files in the report and the in-place upgrade will not be affected. (RHEL-40115)

  • By default, the logrotate is not active after the upgrade. The logrotate was previously managed by cron in RHEL 8 and earlier. In RHEL 9, it is managed by systemd. To activate logrotate persistently, run the following command after the upgrade: 

    # systemctl enable --now logrotate.timer
    Copy to Clipboard Toggle word wrap
  • If you use an HTTP proxy, Red Hat Subscription Manager must be configured to use such a proxy, or the subscription-manager command must be executed with the --proxy <hostname> option. Otherwise, an execution of the subscription-manager command fails. If you use the --proxy option instead of the configuration change, the upgrade process fails because Leapp is unable to detect the proxy. To prevent this problem from occurring, manually edit the rhsm.conf file. For more information, see the Red Hat Knowledgebase solution How to configure HTTP Proxy for Red Hat Subscription Management. (BZ#1689294)
  • For systems that require a proxy to access RHEL 9 content, you usually need to configure the use of the proxy by DNF in the /etc/dnf/dnf.conf configuration file. If the current DNF configuration is not compatible with the DNF version on the target system, specify the valid target configuration in the /etc/leapp/files/dnf.conf configuration file. For more information, see the Red Hat Knowledgebase solution How does Leapp work with a proxy?

  • The upgrade might fail with a MountError message when all of the following conditions are met:

    • A mount point that is defined in /etc/fstab contains underscore characters.

    • Another mount point defined in /etc/stab has the same name if the underscore character is replaced with a forward slash.

      For example, having both /var/tmp and /var_tmp mount points defined in /etc/fstab causes the upgrade to fail.

      To prevent this problem, unmount the mount point that contains underscore characters, and comment that mount point out from the /etc/fstab file before the upgrade. You can restore the configuration after the upgrade.

      (RHEL-62737)

  • When upgrading systems by using Red Hat Upgrade Infrastructure (RHUI), the upgrade could fail if the RHUI setup of the system differs from defaults implemented in the in-place upgrade solution RHUI systems expected by the Leapp utility. To resolve this problem, configure the upgrade process to adjust it for your RHUI setup. For more information, see Using RHUI to configure an in-place upgrade.

  • You cannot perform an upgrade on systems with the kernel-rt package installed. To prevent this problem, run the following command before the upgrade to remove the package during the upgrade process: 

    # echo kernel-rt >>/etc/leapp/transaction/to_remove
    Copy to Clipboard Toggle word wrap

    (RHEL-95215)

  • The in-place upgrade might fail on systems with Non-Volatile Memory Express over Fibre Channel (NVME-FC). (#RHEL-46807)

  • Systems that were upgraded from RHEL 7 to RHEL 8 might contain leftover upgrade-related files that could cause issues with the RHEL 8 to RHEL 9 in-place upgrade. To prevent these issues, complete the following steps:

    1. If you already installed the RHEL 8 to RHEL 9 upgrade packages, remove them: 

      # dnf remove "*leapp*" -y
      Copy to Clipboard Toggle word wrap

    2. Remove leftover RHEL 7 to RHEL 8 upgrade-related files: 

      # rm -rf /usr/share/leapp-repository/repositories
      Copy to Clipboard Toggle word wrap

    3. Install the RHEL 8 to RHEL 9 upgrade packages: 

      # dnf install leapp-upgrade -y
      Copy to Clipboard Toggle word wrap
  • The in-place upgrade to RHEL 9.7 fails on systems that have enabled secure boot. The kernel on RHEL 9.7 has a new signature that is not currently accepted by the RHEL 8.10 bootloader. The upgrade to RHEL 9.4 and 9.6 is not affected. (RHEL-126741)

9.4. Obtaining support
Copy link

To open a support case, select RHEL 8 as the product, and provide a sosreport from your system.

  • To generate a sosreport on your system, run: 
# sosreport
Copy to Clipboard Toggle word wrap

Note that you can leave the case ID empty.

For more information about generating a sosreport, see the Red Hat Knowledgebase solution What is an sosreport and how to create one in Red Hat Enterprise Linux?.

For more information about opening and managing a support case on the Customer Portal, see the Red Hat Knowledgebase solution, How do I open and manage a support case on the Customer Portal?.

Appendix A. RHEL 8 repositories
Copy link

Before the upgrade, ensure you have appropriate repositories enabled as described in step 6 of the procedure in Preparing a RHEL 8 system for the upgrade.

If you plan to use Red Hat Subscription Manager during the upgrade, you must enable the following repositories before the upgrade by using the subscription-manager repos --enable repository_id command:

Expand
Table A.1. RHEL 8 repositories
ArchitectureRepositoryRepository ID

64-bit Intel and AMD

Base

rhel-8-for-x86_64-baseos-rpms

AppStream

rhel-8-for-x86_64-appstream-rpms

64-bit ARM

Base

rhel-8-for-aarch64-baseos-rpms

Extras

rhel-8-for-aarch64-appstream-rpms

IBM POWER (little endian)

Base

rhel-8-for-ppc64le-baseos-rpms

AppStream

rhel-8-for-ppc64le-appstream-rpms

IBM Z

Base

rhel-8-for-s390x-baseos-rpms

AppStream

rhel-8-for-s390x-appstream-rpms

You can enable the following repositories before the upgrade by using the subscription-manager repos --enable repository_id command:

Expand
Table A.2. Voluntary RHEL 8 repositories
ArchitectureRepositoryRepository ID

64-bit Intel and AMD

Code Ready Linux Builder

codeready-builder-for-rhel-8-x86_64-rpms

Supplementary

rhel-8-for-x86_64-supplementary-rpms

64-bit ARM

Code Ready Linux Builder

codeready-builder-for-rhel-8-aarch64-rpms

Supplementary

rhel-8-for-aarch64-supplementary-rpms

IBM POWER (little endian)

Code Ready Linux Builder

codeready-builder-for-rhel-8-ppc64le-rpms

Supplementary

rhel-8-for-ppc64le-supplementary-rpms

IBM Z

Code Ready Linux Builder

codeready-builder-for-rhel-8-s390x-rpms

Supplementary

rhel-8-for-s390x-supplementary-rpms

Note

If you have enabled a RHEL 8 Code Ready Linux Builder or a RHEL 8 Supplementary repository before an in-place upgrade, Leapp enables the RHEL 8 CodeReady Linux Builder or the RHEL 8 Supplementary repositories, respectively. For more information, see the Package manifest.

If you decide to use custom repositories, enable them per instructions in Configuring custom repositories.

Appendix B. RHEL 9 repositories
Copy link

If your system is registered to the Red Hat Content Delivery Network (CDN) using the Red Hat Subscription Manager (RHSM), RHEL 9 repositories are automatically enabled during the in-place upgrade. However, on systems registered to Red Hat Satellite using RHSM, you must manually enable and synchronize both RHEL 8 and RHEL 9 repositories before running the pre-upgrade report.

Note

Make sure to enable the target OS version of each repository, for example 9.6. If you have enabled only the RHEL 9 version of the repositories, the in-place upgrade is inhibited.

If you plan to use Red Hat Satellite during the upgrade, you must enable and synchronize at least the following RHEL 9 repositories before the upgrade using either the Satellite web UI or the hammer repository-set enable and hammer product synchronize commands:

Expand
Table B.1. RHEL 9 repositories
ArchitectureRepositoryRepository IDRepository nameRelease version

64-bit Intel and AMD

BaseOS

rhel-9-for-x86_64-baseos-rpms

Red Hat Enterprise Linux 9 for x86_64 - BaseOS (RPMs)

x86_64 <target_os_version>

AppStream

rhel-9-for-x86_64-appstream-rpms

Red Hat Enterprise Linux 9 for x86_64 - AppStream (RPMs)

x86_64 <target_os_version>

64-bit ARM

BaseOS

rhel-9-for-aarch64-baseos-rpms

Red Hat Enterprise Linux 9 for ARM 64 - BaseOS (RPMs)

aarch64 <target_os_version>

AppStream

rhel-9-for-aarch64-appstream-rpms

Red Hat Enterprise Linux 9 for ARM 64 - AppStream (RPMs)

aarch64 <target_os_version>

IBM Power (little endian)

BaseOS

rhel-9-for-ppc64le-baseos-rpms

Red Hat Enterprise Linux 9 for Power, little endian - BaseOS (RPMs)

ppc64le <target_os_version>

AppStream

rhel-9-for-ppc64le-appstream-rpms

Red Hat Enterprise Linux 9 for Power, little endian - AppStream (RPMs)

ppc64le <target_os_version>

IBM Z

BaseOS

rhel-9-for-s390x-baseos-rpms

Red Hat Enterprise Linux 9 for IBM z Systems - BaseOS (RPMs)

s390x <target_os_version>

AppStream

rhel-9-for-s390x-appstream-rpms

Red Hat Enterprise Linux 9 for IBM z Systems - AppStream (RPMs)

s390x <target_os_version>

Replace <target_os_version> with the target OS version, for example 9.6.

Legal Notice
Copy link

Copyright © Red Hat.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red Hat