Converting from an RPM-based Linux distribution to RHEL

Red Hat Enterprise Linux 8

Instructions for a conversion from Alma Linux, CentOS Linux, Oracle Linux, or Rocky Linux to Red Hat Enterprise Linux 7 and Red Hat Enterprise Linux 8

Red Hat Customer Content Services

Abstract

This document provides instructions on how to convert your operating system from Alma Linux, CentOS Linux, Oracle Linux, or Rocky Linux to RHEL 7 and RHEL 8.

Preface

This document provides instructions on how to convert your operating system from the following Linux distributions to Red Hat Enterprise Linux (RHEL) 7 or RHEL 8:

  • Alma Linux
  • CentOS Linux
  • Oracle Linux
  • Rocky Linux

The conversion is performed by the Convert2RHEL utility.

Note

The conversion from Scientific Linux to RHEL is not currently supported by Red Hat. For information about an unsupported conversion, see How to perform an unsupported conversion from a RHEL-derived Linux distribution to RHEL.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Providing feedback on Red Hat documentation

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

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 conversion paths

Important

Red Hat recommends that you seek the support of Red Hat Consulting services to ensure that the conversion process is smooth.

Currently, it is possible to convert your systems from the following Linux distributions and versions to the corresponding minor version of RHEL listed in Table 1.1.

Table 1.1. Supported conversion paths

Source OSSource versionTarget OS and versionProduct VariantAvailable Conversion Methods

Alma Linux

8.9

RHEL 8.9

N/A

Command-line interface, Satellite

8.8

RHEL 8.8 EUS

N/A

Command-line interface, Satellite

8.6

RHEL 8.6 EUS

N/A

Command-line interface, Satellite

CentOS Linux

8.5

RHEL 8.5

N/A

Command-line interface, Satellite

7.9

RHEL 7.9

Server

Command-line interface, Satellite, Red Hat Insights

Oracle Linux

8.9

RHEL 8.9

N/A

Command-line interface, Satellite

7.9

RHEL 7.9

Server

Command-line interface, Satellite

Rocky Linux

8.9

RHEL 8.9

N/A

Command-line interface, Satellite

8.8

RHEL 8.8 EUS

N/A

Command-line interface, Satellite

8.6

RHEL 8.6 EUS

N/A

Command-line interface, Satellite

Important

Due to a known issue, Alma Linux 8 systems cannot perform a supported conversion to RHEL at this time. For more information, see Known issues and limitations.

Because the last available minor version of CentOS Linux is CentOS Linux 8.5, it is not possible to convert from CentOS Linux 8 directly to the latest available minor version of RHEL 8. It is recommended to update your system to the latest version of RHEL after the conversion.

In addition to the above supported conversion paths, it is also possible to perform an unsupported conversion from Scientific Linux to RHEL. For information about unsupported conversions, see How to perform an unsupported conversion from a RHEL-derived Linux distribution to RHEL.

Important

Conversions from CentOS Stream to RHEL are not currently possible.

For information about Red Hat’s support policy for Linux distribution conversions, see Convert2RHEL Support Policy.

Chapter 2. Conversion methods

Depending on your requirements, you can convert to RHEL by using one of the following methods:

  • Converting by using the command-line interface - Use this method to convert a small number of servers, or to convert a large number of servers at scale by using custom automation.

    Note

    If you have a Satellite subscription but plan to convert by using the command-line interface, you can access the required RHEL packages through Satellite instead of using the Red Hat Content Delivery Network (CDN).

    For more information about how to convert by using the command-line interface, see Planning a RHEL conversion and Converting using the command-line.

  • Converting by using Satellite - Use this method to convert a large number of servers at scale. To convert by using Satellite, you must have a Satellite subscription. For more information about how to convert by using Satellite, see Converting a Host to Red Hat Enterprise Linux.
  • Converting by using Red Hat Insights - Use this method to convert multiple systems in a user-friendly GUI interface without needing a Satellite subscription. Systems must be connected to the internet. Systems are fully onboarded with Red Hat Insights after the conversion.

    For more information about how to convert by using Red Hat Insights, see Planning a RHEL conversion and Converting using Insights.

Chapter 3. Planning a RHEL conversion

The automated conversion process is performed on a running system. The Convert2RHEL utility replaces all RPM packages from the original Linux distribution by their RHEL version. At the end of the process, it is necessary to restart the system to boot the RHEL kernel.

Packages that are available only in the original distribution and do not have corresponding counterparts in RHEL repositories, and third-party packages, which originate neither from the original Linux distribution nor from RHEL, are not affected by the conversion. Red Hat does not provide support for third-party packages that are left unchanged during the conversion process. See the Red Hat policy on supporting third-party software.

Note

The Convert2RHEL utility does not directly affect local users and their data in the /home and /srv directories. However, Convert2RHEL cannot control actions that RPM package scriptlets perform during the conversion process.

You should consider the following before converting your system to RHEL:

  • Architecture - The source OS must be installed on a system with 64-bit Intel architecture. It is not possible to convert with other system architectures.
  • Security - Systems in FIPS mode are not supported for conversion.
  • Kernel - Systems using kernel modules that do not exist in RHEL kernel modules are not currently supported for conversion. Red Hat recommends disabling or uninstalling foreign kernel modules before the conversion and then enabling or reinstalling those kernel modules afterwards. Unsupported kernel modules include:

    • Kernel modules for specialized applications, GPUs, network drivers, or storage drivers
    • Custom compiled kernel modules built by DKMS
  • Public clouds - Conversions on public clouds are supported in the following situations:

    • Alma Linux, CentOS Linux, and Rocky Linux - Using Red Hat Subscription Manager (RHSM) for the following:

      • Images on Amazon Web Services (AWS), Microsoft Azure, and Google Cloud with no associated software cost.
      • User-provided custom images on all public clouds
    • Oracle Linux - Using RHSM for user-provided custom images on all public clouds.

      Convert2RHEL is unable to access RHEL packages through Red Hat Update Infrastructure (RHUI) during the conversion of both CentOS Linux and Oracle Linux.

  • High Availability - Systems using high availability cluster software by Red Hat or third parties are not currently tested or supported for conversion to RHEL. Red Hat recommends migrating to newly installed RHEL systems to ensure the integrity of these environments.
  • Identity Management - Performing an in-place conversion of a FreeIPA server is not supported. For more information about how to migrate a FreeIPA deployment to IdM, see Migrating to IdM on RHEL 7 from FreeIPA on non-RHEL Linux distributions and Migrating to IdM on RHEL 8 from FreeIPA on non-RHEL Linux distributions.

Chapter 4. Converting using the command-line

You can perform the conversion from Alma Linux, CentOS Linux, Oracle Linux, or Rocky Linux to RHEL by using the command-line interface.

4.1. Preparing for a RHEL conversion

This procedure describes the steps that are necessary before performing the conversion from Alma Linux, CentOS Linux, Oracle Linux, or Rocky Linux to Red Hat Enterprise Linux (RHEL).

Prerequisites

  • You have verified that your system is supported for conversion to RHEL. See Supported conversion paths for more information.
  • You have stopped important applications, database services, and any other services that store data to reduce the risk of data integrity issues.
  • You have temporarily disabled antivirus software to prevent the conversion from failing.
  • You have disabled or adequately reconfigured any configuration management system, such as Salt, Chef, Puppet, Ansible, to not attempt to restore the original system.
  • The sos package is installed. You must use this package to generate an sosreport that is required when opening a support case for the Red Hat Support team.
  • You have created an activation key in Satellite or RHSM. For more information, see Managing activation keys in Satellite documentation and Getting started with activation keys on the Hybrid Cloud Console in RHSM documentation.

Procedure

  1. Back up your system and verify that it can be restored if needed.
  2. Check Known issues and limitations and verify that your system is supported for conversion. Apply workarounds where applicable.
  3. Ensure that the standard kernel is the booted kernel:

    • Alma Linux: the standard Alma Linux Kernel
    • CentOS Linux: the standard CentOS Linux kernel
    • Oracle Linux: the Red Hat Compatible Kernel (RHCK)
    • Rocky Linux: the standard Rocky Linux Kernel

      If the kernel your system is booted into is not the standard kernel, for example CentOS realtime kernel or Oracle Linux Unbreakable Enterprise Kernel (UEK), change the default kernel to the standard kernel and reboot your system to apply the changes.

  4. If converting from CentOS Linux 8, remove any CentOS Stream packages from your system. CentOS Stream is not currently supported for conversion, and the conversion might fail if any packages are present on the system.
  5. If you are converting with a firewall, using Red Hat Satellite, or through a proxy server, ensure that you have access to the following connections:

  6. If converting from CentOS Linux 8, update the CentOS repository URLs:

    # sed -i 's/^mirrorlist/#mirrorlist/g' /etc/yum.repos.d/CentOS-*
    # sed -i 's|#baseurl=http://mirror.centos.org|baseurl=https://vault.centos.org|g' /etc/yum.repos.d/CentOS-*
    Important

    CentOS Linux 8 has reached end of life. For more information, see CentOS Linux EOL.

  7. Install Convert2RHEL:

    1. Download the Red Hat GPG key:

      # curl -o /etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release https://www.redhat.com/security/data/fd431d51.txt
    2. Install the Convert2RHEL repository file:

      # curl -o /etc/yum.repos.d/convert2rhel.repo https://ftp.redhat.com/redhat/convert2rhel/<version_number>/convert2rhel.repo

      Replace version_number with the appropriate major version of the OS, for example 7 or 8.

      Note

      You must perform the conversion with the latest version of the Convert2RHEL repository file. If you had previously installed an earlier version of the repository file, remove the earlier version and install the current version.

    3. Install the Convert2RHEL utility:

      # yum -y install convert2rhel
  8. Ensure you have access to RHEL packages through one of the following methods:

    1. Red Hat Content Delivery Network (CDN) through Red Hat Subscription Manager (RHSM). You must have a Red Hat account and an appropriate RHEL subscription to access RHSM. Note that the OS will be converted to the corresponding minor version of RHEL per Table 1.1.
    2. Red Hat Satellite in a version that has Full or Maintenance support. For more information, see Red Hat Satellite Product Life Cycle.

      Note

      Ensure that the Satellite server meets the following conditions:

      • Satellite has a subscription manifest with RHEL repositories imported. For more information, see the Managing Subscriptions chapter in the Content Management Guide for the particular version of Red Hat Satellite, for example, for version 6.10.
      • All required repositories are enabled and synchronized with the latest target OS updates and published on Satellite. Enable at minimum the following repositories for the appropriate major version of the OS:

        • Red Hat Enterprise Linux 7 Server RPMs x86_64 7Server
        • Red Hat Enterprise Linux 8 for x86_64 - AppStream RPMs <target_os>
        • Red Hat Enterprise Linux 8 for x86_64 - BaseOS RPMs <target_os>

      Replace target_os with 8.5 for CentOS Linux conversions and 8.8 or 8.6 for Alma Linux, Oracle Linux, or Rocky Linux conversions.

    3. Custom repositories configured in the /etc/yum.repos.d/ directory and pointing to a mirror of the target OS repositories. Use custom repositories for systems that have access to only local networks or portable media and therefore cannot access Red Hat CDN through RHSM. Make sure that the repositories contain the latest content available for that RHEL minor version to prevent downgrading and potential conversion failures. For more information, see Creating a Local Repository and Sharing With Disconnected/Offline/Air-gapped Systems.

      Note

      RHEL 8 content is distributed through two default repositories, BaseOS and AppStream. If you are accessing RHEL packages through custom repositories, you must configure both default repositories for a successful conversion. When running the Convert2RHEL utility, make sure to enable both repositories using the --enablerepo option. For more information about RHEL 8 repositories, see Considerations in adopting RHEL 8.

  9. If you are accessing RHEL packages through a Red Hat Satellite server, download the consumer RPM to the /usr/share/convert2rhel/subscription-manager/ directory:

    # curl --insecure --output /usr/share/convert2rhel/subscription-manager/katello-ca-consumer-latest.noarch.rpm https://<satellite.example.com>/pub/katello-ca-consumer-latest.noarch.rpm

    Replace satellite.example.com with the hostname of your Satellite server.

  10. If you are converting by using RHSM or Red Hat Satellite and have not yet registered the system, update the /etc/convert2rhel.ini file to include the following data:

    [subscription_manager]
    org = <organization_ID>
    activation_key = <activation_key>

    Replace organization_id and activation_key with the organization ID and activation key from the Red Hat Customer Portal if you are using Red Hat CDN or the Satellite web UI if you are using Red Hat Satellite.

  11. Temporarily disable antivirus software to prevent the conversion from failing.
  12. If you are accessing RHEL packages by using custom repositories, disable these repositories. The Convert2RHEL utility enables the custom repositories during the conversion process.
  13. Update the original OS to the minor version supported for conversion as specified in Table 1.1 and then reboot the system.

    You must perform the conversion with the latest packages from the minor version of the OS that is supported for conversion to use the rollback feature in case the conversion fails. For more information, see Conversion rollback.

4.2. Reviewing the pre-conversion analysis report

To assess whether your systems can be converted to RHEL, run the RHEL pre-conversion analysis. The pre-conversion analysis generates a report that summarizes potential problems and suggests recommended solutions. The report also helps you decide whether it is possible or advisable to proceed with the conversion to RHEL.

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

Important

The pre-conversion analysis report cannot identify all inhibiting problems with your system. As a result, issues might still occur during the conversion even after you have reviewed and remediated all problems in the report.

Prerequisites

Procedure

  1. On your Alma Linux, CentOS Linux, Oracle Linux, or Rocky Linux system, run the pre-conversion analysis:

    #  convert2rhel analyze
    • If you are converting to RHEL 8.8 and have an Extended Upgrade Support (EUS), add the --eus option. This option ensures that your system receives important security updates delivered to EUS repositories only. Conversions to RHEL 8.6 use EUS repositories automatically.
  2. The pre-conversion analysis runs a series of tests to determine whether your system can be converted to RHEL. After the analysis is complete, review the status and details of each completed test in the pre-conversion report in the terminal. Non-successful tests contain a description of the issue, a diagnosis of the possible cause of the issue, and, if applicable, a recommended remediation.

    Each test results in one of the following statuses:

    • Success - The test was successful and there are no issues for this component.
    • Error - The test encountered an issue that would cause the conversion to fail because it is very likely to result in a deteriorated system state. This issue must be resolved before converting.
    • Overridable - The test encountered an issue that would cause the conversion to fail because it is very likely to result in a deteriorated system state. This issue must be either resolved or manually overridden before converting.
    • Warning - The test encountered an issue that might cause system and application issues after the conversion. However, this issue would not cause the conversion to fail.
    • Skip - Could not run this test because of a prerequisite test failing. Could cause the conversion to fail.
    • Info - Informational with no expected impact to the system or applications.

      For example:

      ========== Warning (Review and fix if needed) ==========
      
      (WARNING) PACKAGE_UPDATES::PACKAGE_NOT_UP_TO_DATE_MESSAGE - Outdated packages detected
           Description: Please refer to the diagnosis for further information
           Diagnosis: The system has 4 package(s) not updated based on the enabled system repositories.
          List of packages to update: openssh-server openssh openssh-clients.
      
          Not updating the packages may cause the conversion to fail.
          Consider updating the packages before proceeding with the conversion.
           Remediation: [No further information given]
  3. After reviewing the report and resolving all reported issues, repeat steps 1-2 to rerun the analysis and confirm that there are no issues outstanding.

4.3. Converting to a RHEL system

This procedure describes the steps necessary to convert your system from Alma Linux, CentOS Linux, Oracle Linux, or Rocky Linux to Red Hat Enterprise Linux (RHEL).

Note

By default, Red Hat collects conversion-related data, such as the conversion start and end times and whether the conversion was successful, for utility usage analysis. To disable data collection, set the CONVERT2RHEL_DISABLE_TELEMETRY environment variable to 1.

Procedure

  1. Start the Convert2RHEL utility:

    # convert2rhel
    • To display all available options, use the --help (-h) option.
    • If you are converting by using custom repositories instead of RHSM, add the --no-rhsm and --enablerepo <RHEL_RepoID1> --enablerepo <RHEL_RepoID2> options. Replace RHEL_RepoID with your custom repository configured in the /etc/yum.repos.d/ directory, for example, rhel-7-server-rpms or rhel-8-baseos and rhel-8-appstream.
    • If you are converting to RHEL 7, you can manually enable RHEL 7 Extras or Optional repositories by using the --enablerepo option to replace additional packages with their RHEL counterparts. Note that packages in the Optional repository are unsupported. For more information, see Support policy of the optional and supplementary channels in Red Hat Enterprise Linux.
    • If you are converting to RHEL 8.8 and have an Extended Upgrade Support (EUS), add the --eus option. This option ensures that your system receives important security updates delivered to EUS repositories only. Conversions to RHEL 8.6 use EUS repositories automatically.
  2. Before Convert2RHEL starts replacing packages from the original distribution with RHEL packages, the following warning message is displayed:

    The tool allows rollback of any action until this point.
    By continuing, all further changes on the system will need to be reverted manually by the user, if necessary.

    Changes made by Convert2RHEL up to this point can be automatically reverted. Confirm that you wish to proceed with the conversion process.

  3. Wait until Convert2RHEL installs the RHEL packages and finishes successfully.
  4. Recommended: If you used custom repositories for the conversion, register and subscribe your RHEL system. For more information, see How to register and subscribe a system offline to the Red Hat Customer Portal?.
  5. At this point, the system still runs with the original distribution kernel loaded in RAM. Reboot the system to boot the newly installed RHEL kernel.

    # reboot
  6. Review the list of the third-party packages and remove unnecessary packages from the original OS that remained unchanged. These are typically packages that do not have a RHEL counterpart. To get a list of these packages, use:

    # yum list extras --disablerepo="*" --enablerepo=<RHEL_RepoID>

    Replace RHEL_RepoID with your repository.

    Note

    On Alma Linux 8.8 systems, some Alma Linux packages are not replaced with RHEL packages. See Known issues and limitations for more information.

  7. Optional: Perform an in-place upgrade to RHEL 9 to ensure your system is updated with the latest enhancements, security features, and bug fixes. For more information, see the Upgrading from RHEL 7 to RHEL 8 and Upgrading from RHEL 8 to RHEL 9 guides. Note that if you have converted to RHEL 7, you must first perform the in-place upgrade from RHEL 7 to RHEL 8, and then from RHEL 8 to RHEL 9.

Verification

  • Verify that your system operates as expected. If necessary, reconfigure system services after the conversion and fix dependency errors. For more information, see Fixing dependency errors.

Chapter 5. Converting using Insights

You can perform the conversion from CentOS Linux 7 to RHEL 7 by using Red Hat Insights.

5.1. Preparing for a RHEL conversion using Insights

Before running the pre-conversion analysis by using Red Hat Insights and performing the conversion, you must first complete all necessary preparation steps.

Prerequisites

  • You are planning to convert CentOS Linux 7 systems to Red Hat Enterprise Linux (RHEL) 7. Conversions from CentOS Linux 8 and other Linux distributions must be performed in the command-line or Satellite.
  • You have an account and activation key at Red Hat Customer Portal. For more information, see Getting started with activation keys on the Hybrid Cloud Console.
  • You have stopped important applications, database services, and any other services that store data to reduce the risk of data integrity issues.
  • You have temporarily disabled antivirus software to prevent the conversion from failing.
  • You have disabled or adequately reconfigured any configuration management system, such as Salt, Chef, Puppet, Ansible, to not attempt to restore the original system.
  • The sos package is installed. You must use this package to generate an sosreport that is required when opening a support case for the Red Hat Support team.
  • You have enabled Simple Content Access (SCA). Red Hat accounts created after July 15, 2022 have SCA enabled by default.

Procedure

  1. Ensure that you have a RHEL subscription. You can obtain a subscription using one of the following methods:

    1. Get a no-cost RHEL Developer Subscription for Individuals. The Developer Subscription is limited to sixteen servers.
    2. Start a 60-day free trial for a RHEL subscription. You can cancel this trial at any time.
    3. Contact the Red Hat Sales team for assistance. If you plan to convert a large number of servers, Red Hat recommends coordinating with the Sales team.
  2. Back up your systems and verify that they can be restored if needed.
  3. Check Known issues and limitations and verify that your system is supported for conversion. Apply workarounds where applicable.
  4. Ensure that the standard CentOS Linux kernel is the booted kernel. If the kernel your system is booted into is not the standard kernel, change the default kernel to the standard kernel and reboot your system to apply the changes. For more information, see Making Persistent Changes to a GRUB 2 Menu Using the grubby Tool.
  5. If you are converting with a firewall or through a proxy server, ensure that you have access to the following connections:

  6. Install the Red Hat client tools:

    1. Download the Red Hat GPG key:

      # curl -o /etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release https://www.redhat.com/security/data/fd431d51.txt
    2. Install the client-tools repository file:

      # curl -o /etc/yum.repos.d/client-tools.repo https://ftp.redhat.com/redhat/client-tools/client-tools-for-rhel-7-server.repo
    3. Install the client tools packages:

      # yum -y install subscription-manager subscription-manager-rhsm-certificates rhc rhc-worker-script insights-client
  7. Enable Remote Host Configuration, register your systems with Red Hat Subscription Manager (RHSM), and connect your systems with Red Hat Insights:

    # rhc connect --activation-key <activation_key> --organization <organization_ID>

    Replace organization_id and activation_key with the organization ID and activation key from the Red Hat Customer Portal. For more information on Remote Host Configuration, see the Remote Host Configuration (rhc) Knowledgebase article.

Verification

  1. Log in to the Red Hat Hybrid Cloud Console and go to Red Hat Insights > RHEL > Inventory > Systems.
  2. Verify that your CentOS Linux systems appear as expected.
Note

The only Red Hat Insights service you can use with registered CentOS Linux systems is the RHEL conversion. All other Insights services are available only after the conversion to RHEL.

5.2. Reviewing the pre-conversion analysis report using Insights

To assess whether your CentOS Linux systems can be converted to RHEL, run the Pre-conversion analysis for converting to RHEL task. The pre-conversion analysis generates a report that summarizes potential problems and suggests recommended solutions. The report also helps you decide whether it is possible or advisable to proceed with the conversion to RHEL.

Prerequisites

Procedure

  1. Log in to the Red Hat Hybrid Cloud Console and go to Red Hat Insights > RHEL > Automation toolkit > Tasks.
  2. Locate the Pre-conversion analysis for converting to RHEL task and click Run task.
  3. Select the CentOS Linux 7 systems that you want to analyze for conversion and click Execute task.

    Note

    The pre-conversion analysis can take up to an hour to complete.

    The pre-conversion analysis utility generates a new report in the Activity tab. Select the report to view a summary of issues found in each system. You can also review further by selecting a system to view each issue and, when applicable, a potential remediation in detail.

    Figure 5.1. Pre-conversion analysis for converting to RHEL

    Pre-conversion analysis for converting to RHEL

    Each issue is assigned a severity level:

    • Inhibitor: Would cause the conversion to fail because it is very likely to result in a deteriorated system state. This issue must be resolved before converting.
    • Skipped: Could not run this test because of a prerequisite test failing. Could cause the conversion to fail.
    • Warning: Would not cause the conversion to fail. System and application issues might occur after the conversion.
    • Info: Informational with no expected impact to the system or applications.
  4. After reviewing the report and resolving all reported issues, click Run task again to rerun the analysis and confirm that there are no issues outstanding.

5.3. Converting to a RHEL system using Insights

After running the Pre-conversion analysis for converting to RHEL task and resolving all reported issues, you can convert your CentOS Linux 7 systems to RHEL 7.

Prerequisites

Procedure

  1. Log in to the Red Hat Hybrid Cloud Console and go to Red Hat Insights > RHEL > Automation toolkit > Tasks.
  2. Locate the Convert to RHEL from CentOS 7 Linux task and click Run task.
  3. Select the CentOS Linux 7 systems that you want to convert to RHEL and click Execute task.

    Note

    The conversion process can take up to an hour to complete.

  4. Go to the Activity tab and select the newly generated conversion report.
  5. Review each system and message:

    • If a system has been successfully converted with no issues, reboot the system and proceed to the next step.
    • If the system was not converted, review the message for more information on the found problems and how to resolve them. Additionally, verify the following:

    • If the conversion timed out without completing, verify that the system is running and retry at another time. If issues persist, contact Support.

      Figure 5.2. Convert to RHEL from CentOS 7 Linux

      Convert to RHEL from CentOS 7 Linux
  6. After rebooting the system that has been successfully converted, remove third-party packages from the original OS that remained unchanged. These are typically packages that do not have a RHEL counterpart. To get a list of these packages, use:

    # yum list extras --disablerepo="*" --enablerepo=<RHEL_RepoID>

    Replace RHEL_RepoID with your repository.

  7. Optional: Perform an in-place upgrade to RHEL 9 to ensure your system is updated with the latest enhancements, security features, and bug fixes. For more information, see the Upgrading from RHEL 7 to RHEL 8 and Upgrading from RHEL 8 to RHEL 9 guides.

Chapter 6. Conversion rollback

The Convert2RHEL utility provides a limited rollback functionality under the following conditions:

  • If Convert2RHEL has been run in the analyze mode, the utility performs a rollback of all changes it made.
  • If the utility fails or is stopped by the user, only changes performed until Convert2RHEL starts replacing packages from the original distribution with RHEL packages can be reverted. This moment is indicated by the warning message:

    The tool allows rollback of any action until this point.
    By continuing all further changes on the system will need to be reverted manually by the user, if necessary.

    followed by a question whether you wish to continue with the process.

    Note

    If the -y option is used with the convert2rhel command, the question indicating the moment after which the automated rollback is no longer possible is skipped.

Warning

If the conversion process is canceled or fails after Convert2RHEL has started the package replacement phase, the system can become dysfunctional. In such a case, manual fixes will be needed. Please contact Red Hat Consulting services for assistance.

Chapter 7. Troubleshooting conversions

This chapter lists troubleshooting resources and tips.

7.1. Troubleshooting resources

To help you troubleshoot issues that can occur during the conversion process, review the log messages that are printed to the console and log files.

Console Output

By default, only info, warning, error, and critical log level messages are printed to the console output by the Convert2RHEL utility. To also print debug messages, use the --debug option with the convert2rhel command.

Logs

  • The /var/log/convert2rhel/convert2rhel.log file lists debug, info, warning, error, and critical messages.
  • The /var/log/convert2rhel/rpm_va.log file lists all package files on the unconverted system that a user has modified. This output is generated by the rpm -Va command, which is run automatically unless the --no-rpm-va option is used with the convert2rhel command.

7.2. Fixing dependency errors

During a conversion from a different Linux distribution to RHEL, certain packages might be installed without some of their dependencies.

Prerequisites

Procedure

  1. Identify dependencies errors:

    # yum check dependencies

    If the command displays no output, no further actions are required.

  2. To fix dependency errors, reinstall the affected packages. During this operation, the yum utility automatically installs missing dependencies. If the required dependencies are not provided by repositories available on the system, install those packages manually.

7.3. Troubleshooting issues with Red Hat Insights conversions

The following issues might occur when using Red Hat Insights to convert to RHEL.

7.3.1. Missing systems in pre-conversion analysis task

When running the Pre-conversion analysis for converting to RHEL task in Red Hat Insights, CentOS Linux 7 systems that appeared correctly in RHEL Inventory might not appear in the list of available systems to run the pre-conversion analysis on. This issue occurs when the Remote Host Configuration (RHC) is disconnected.

Procedure

  1. Log in to the Red Hat Hybrid Cloud Console and go to Red Hat Insights > RHEL > Inventory > Systems.
  2. Select the affected system from the table.
  3. In the General Information tab, go to the System Status card and verify the RHC status:

    1. If the RHC status is Connected, RHC is connected correctly.
    2. If the RHC status is Not available, RHC is disconnected. Proceed to the next step to reconnect RHC.
  4. Unregister the system in your terminal:

    # rhc disconnect
  5. To help with troubleshooting, set the RHC systemd service (rhcd) logging to the highest level:

    # sed -ie 's%error%trace%' /etc/rhc/config.toml
  6. Register your system with Red Hat Insights and re-enable RHC in your terminal:

    # insights-client --register
    # rhc connect -a <activation_key> -o <organization_ID>

    Replace activation_key and organization_ID with the activation key and organization ID from the Red Hat Customer Portal.

Verification

  • Verify that you can select the system in the Pre-conversion analysis for converting to RHEL task.

    If the system still does not appear correctly, review error messages from rhcd and the insights-client tool:

    # journalctl -u rhcd
    # less /var/log/insights-client/insights-client.log

7.3.2. Pre-conversion analysis task fails to complete

After running the Pre-conversion analysis for converting to RHEL task, one or more of the systems can fail to generate a report with the error message Task failed to complete for an unknown reason. Retry this task at a later time. If this issue occurs, complete the steps below to troubleshoot.

Procedure

  1. Verify if the affected system is unavailable, for example because of a network accessibility issue or because the system is shut off.
  2. Review the RHC systemd service (rhcd) for errors:

    1. Stop rhcd in your terminal:

      # systemctl stop rhcd
    2. Set rhcd logging to the highest level:

      # sed -ie 's%error%trace%' /etc/rhc/config.toml
    3. Restart rhcd:

      # systemctl start rhcd
    4. Review error messages posted by rhcd:

      # journalctl -u rhcd
  3. Review the rhc-worker-script log file for errors:

    # less /var/log/rhc-worker-script/rhc-worker-script.log

7.4. Known issues and limitations

The following issues and limitations are known to occur during the conversion:

  • Systems that connect to the Internet using an HTTP proxy server cannot convert using Red Hat CDN or Satellite through RHSM. To work around this problem, enable HTTP proxy for yum and then configure the HTTP proxy for RHSM:

    1. Configure yum to use an HTTP proxy as described in How to enable proxy settings for yum command on RHEL?
    2. Install the subscription-manager package:

      1. Download the Red Hat GPG key:

        # curl -o /etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release https://www.redhat.com/security/data/fd431d51.txt
      2. Install a repository file for the client-tools repository that contains the subscription-manager package:

        • For CentOS Linux and Oracle Linux 7:

          # curl -o /etc/yum.repos.d/client-tools.repo https://ftp.redhat.com/redhat/client-tools/client-tools-for-rhel-7-server.repo
        • For Alma Linux, CentOS Linux, Oracle Linux, or Rocky Linux 8:

          # curl -o /etc/yum.repos.d/client-tools.repo https://ftp.redhat.com/redhat/client-tools/client-tools-for-rhel-8-x86_64.repo
      3. Install the following subscription-manager packages:

        # yum -y install subscription-manager subscription-manager-rhsm-certificates
    3. Configure HTTP proxy for RHSM as described in How to configure HTTP Proxy for Red Hat Subscription Management.
    4. Enable Simple Content Access (SCA). For more information, see the Simple Content Access Knowledgebase article.
    5. Register the system with RHSM:

      # subscription-manager register --org <organization_id> --activationkey <activation_key>

      Replace organization_id and activation_key with the organization ID and activation key from the Red Hat Customer Portal.

    6. Remove the organization ID and activation key from the /etc/convert2rhel.ini file.
    7. Perform the conversion to RHEL:

      # convert2rhel

      (RHELC-559)

  • UEFI systems with Secure Boot enabled are not supported for conversion. To work around this issue, disable Secure Boot before the conversion and then re-enable after the conversion is complete. (RHELC-138)
  • If you are converting by using Red Hat Insights, running two RHC daemon (rhcd) processes simultaneously prevents the pre-conversion analysis from running as expected. To prevent this issue, run only one rhcd process at a time. (HMS-2629)
  • On Alma Linux 8 systems, an Alma Linux kernel package versioning issue causes some Alma Linux packages to not be replaced with RHEL packages. As a result, the Convert2RHEL utility cannot create a boot entry for RHEL and the system and fails to boot after the conversion. To prevent this issue, complete the following steps after performing the conversion but before rebooting the converted system:

    1. Downgrade the shim-x64 package:

      # dnf downgrade -y shim-x64
    2. Determine the efibootmgr boot partition and the boot entry number for the converted system: # efibootmgr -v Add a new efibootmgr entry:

      # efibootmgr -c -b 0035 -d boot_disk -p <boot_partition> -l \\EFI\\redhat\\shimx64.efi -L "Red Hat Enterprise Linux"

      Replace boot_partition with the boot partition number, for example 1, and boot_disk with the boot disk name, for example /dev/vda.

    3. Remove the existing boot entry for the converted system:

      # efibootmgr -Bb <boot_number>

      Replace boot_number with the boot entry number of the converted system.

      (RHELC-1190)

  • Some inhibitors found in the pre-conversion analysis and conversion can be overridden by setting an environment variable. Due to a known issue, the Hybrid Cloud Console does not recognize when this environment variable is set. As a result, overridable inhibitors must be remediated when converting by using Insights. (RHINENG-5943)
  • If configuration files such as /etc/sysconfig/sshd and /etc/pam.d/sshd have been modified, the conversion is unable to back up those files and fails. To work around this issue, rename one of the conflicting files before performing the conversion. (RHELC-1361)
  • Due to a known issue, Alma Linux 8 systems cannot perform a supported conversion to RHEL at this time. (RHELC-1370)

7.5. Obtaining support

If you experience problems during the conversion, notify Red Hat so that these problems can be addressed.

Important

If you are experiencing problems during the conversion, raise a Support case of Severity 3 or Severity 4 level only. For more details, see Production Support Terms of Service.

Prerequisites

  • The sos package is installed. You must use this package to generate an sosreport that is required when opening a support case for the Red Hat Support team.

Procedure

  • To obtain support, perform either of the following steps:

    • Open a support case:

      • Select RHEL 7 or RHEL 8 as the product, and provide an sosreport from your system.
      • Generate an sosreport on your system:

        # sosreport

        Note that you can leave the case ID empty.

    • Submit a bug report:

      • Open a bug, select RHEL 7 or RHEL 8 as the product, and select convert2rhel as the component.

For details on generating an sosreport, see the 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 article How do I open and manage a support case on the Customer Portal?.

For information about Red Hat’s support policy for Linux distribution conversions, see Convert2RHEL Support Policy.

Chapter 8. Additional resources

Legal Notice

Copyright © 2024 Red Hat, Inc.
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, the Red Hat 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 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.