How to perform an unsupported conversion from a RHEL-derived Linux distribution to RHEL

Updated -

This document provides instructions on how to perform an unsupported conversion of your operating system from a different Linux distribution to Red Hat Enterprise Linux (RHEL).

The conversion is performed by the Convert2RHEL utility, which is available on GitHub, and is unsupported by Red Hat for these scenarios.

The conversion from Alma Linux, CentOS Linux, Oracle Linux, and Rocky Linux to RHEL is supported by Red Hat. For more information, see Converting from a Linux distribution to RHEL using the Convert2RHEL utility. See also Convert2RHEL Support Policy.

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

The Red Hat packages installed as part of a successfully converted system are automatically eligible for Red Hat support. Red Hat support may not be provided for the third-party packages that are left unchanged during the conversion process. See the Red Hat policy on supporting third-party software.

If you encounter any issues with the Convert2RHEL utility, file an issue in GitHub.

How OS conversion works

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 into the RHEL kernel.

NOTE:
Packages that are available only in the original distribution and do not have corresponding counterparts in RHEL repositories, or third-party packages, which originate neither from the original Linux distribution nor from RHEL, are not affected by the conversion.

Differences between supported and unsupported conversions

Red Hat allows conversions from several different RHEL-derived operating systems to RHEL. However, unsupported conversions are not tested by Red Hat and should therefore be performed at your own risk. Supported conversions are thoroughly tested by Red Hat prior to release.

Different conversion paths are available as supported or unsupported conversions. For example, the conversion from Scientific Linux 7 to RHEL 7 is unsupported, while the conversion from CentOS Linux 7 to RHEL 7 is supported. For a full list of unsupported conversion paths, see the table below. For a full list of supported conversion paths, see Supported conversion paths in the Converting from a Linux distribution to RHEL using the Convert2RHEL utility guide.

If you are performing an unsupported conversion, use this Knowledgebase article for instructions about how to prepare your system and perform the conversion. If you are performing a supported conversion, you must use the Converting from a Linux distribution to RHEL using the Convert2RHEL utility guide. If you attempt to perform an unsupported conversion using instructions for supported conversions, or the reverse, you might run into issues during the conversion process.

Available unsupported conversion paths

Currently, it is possible to perform an unsupported conversion of your systems from the following Linux distributions, architectures, and versions to the latest minor version of the corresponding major versions of RHEL listed in the table below.

Source OS Target OS Architecture
CentOS Stream 9 RHEL 9 64-bit architecture
CentOS Stream 8 RHEL 8 64-bit architecture
Scientific Linux 7 RHEL 7 64-bit architecture

In addition to the above unsupported conversion paths, it is also possible to perform a supported conversion from Alma Linux, CentOS Linux, Oracle Linux, or Rocky Linux to RHEL. For information on supported conversions, see Converting from a Linux distribution to RHEL using the Convert2RHEL utility.

RHEL 7 has reached the end of the Maintenance Support Phase. If you are converting to RHEL 7 and plan to stay on RHEL 7, it is strongly recommended to purchase the Extended Life Cycle Support (ELS) add-on subscription. If you plan to convert to RHEL 7 and then immediately upgrade to RHEL 8 or later, an ELS subscription is not needed. For more information, see Red Hat Enterprise Linux Life Cycle.

IMPORTANT
Certain system setups are not currently supported for conversion. For more information, see Known Issues.

Preparing for a conversion

  1. Back up your system and verify that you are able to restore it.
  2. Ensure that the standard kernel is the booted kernel.

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

    • https://cdn.redhat.com
    • https://cdn-public.redhat.com
    • https://subscription.rhsm.redhat.com - required only for systems with firewalls
    • https://*.akamaiedge.net - required only for systems with firewalls
    • https://cert.console.redhat.com

  4. Install the Convert2RHEL utility:

    • 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

    • Install the Convert2RHEL repository file:

      • For conversions to RHEL 7, enter the following command:

        # curl -o /etc/yum.repos.d/convert2rhel.repo https://cdn-public.redhat.com/content/public/repofiles/convert2rhel-for-rhel-7-x86_64.repo

      • For conversions to RHEL 8, enter the following command:

        # curl -o /etc/yum.repos.d/convert2rhel.repo https://cdn-public.redhat.com/content/public/repofiles/convert2rhel-for-rhel-8-x86_64.repo

      • For conversions to RHEL 9, enter the following command:

        # curl -o /etc/yum.repos.d/convert2rhel.repo https://cdn-public.redhat.com/content/public/repofiles/convert2rhel-for-rhel-9-x86_64.repo

    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.

    • Install the Convert2RHEL utility:

      # yum -y install convert2rhel

  5. Ensure that you have an access to RHEL packages through one of the following methods:

    • 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 latest minor version of RHEL for the appropriate major version.
    • 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.8.
      • All required repositories are enabled and synchronized with the latest 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 repository.
        • Red Hat Enterprise Linux 8 for x86_64 - AppStream RPMs 8.8
        • Red Hat Enterprise Linux 8 for x86_64 - BaseOS RPMs 8.8
        • Red Hat Enterprise Linux 9 for x86_64 - BaseOS (RPMs)
        • Red Hat Enterprise Linux 9 for x86_64 - AppStream (RPMs)
      • You have created an activation key in Satellite and assigned the above repositories to the key. For more information, see Managing Activation Keys.
    • Custom repositories configured in the /etc/yum.repos.d/ directory and pointing, for example, to RHEL ISO, FTP, or HTTP. Use custom repositories for systems that have access to only local networks or portable media and therefore cannot access Red Hat CDN through RHSM. Note that the OS will be converted to the version of RHEL provided by these repositories. Make sure that the RHEL minor version is the same or later than the original OS 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.

  6. If you are accessing RHEL packages through a Red Hat Satellite server, register your system with Red Hat Satellite. For more information, see Registering Hosts and Setting Up Host Integration.

  7. If you are converting by using RHSM, 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.

  8. Temporarily disable antivirus software to prevent the conversion from failing.

  9. If you are accessing RHEL packages by using custom repositories, disable these repositories. The Convert2RHEL utility enables the custom repositories during the conversion process.

  10. Update packages from the original OS to the latest version that is available in the repositories accessible from the system, and reboot the system:

    # yum update -y
# reboot

    Without performing this step, the rollback feature will not work correctly, and exiting the conversion in any phase may result in a dysfunctional system.

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.

  1. On your Scientific Linux system, run the pre-conversion analysis:

    #  convert2rhel analyze
    • If you are converting to RHEL 7 and have an Extended Life Cycle Support (ELS) add-on, add the --els option. It is recommended to purchase an ELS add-on if you plan to stay on RHEL 7 to continue receiving support.

  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.

Converting the system

  1. Start the Convert2RHEL utility:

    # convert2rhel -h

    • 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
      • rhel-8-baseos and rhel-8-appstream
      • rhel-9-for-x86_64-baseos-rpms and rhel-9-for-x86_64-appstream-rpms

    • If you are converting to RHEL 7 and have an Extended Life Cycle Support (ELS) add-on, add the --els option. It is recommended to purchase an ELS add-on if you plan to stay on RHEL 7 to continue receiving support.

  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.

  4. Recommended: If you used custom repositories for the conversion, subscribe and update your RHEL system:

    • Install the subscription-manager command line utility:
    # yum install subscription-manager -y

    # yum update -y

  5. At this point, the system still runs with the original distribution kernel loaded in RAM. Reboot the system to boot into the newly installed RHEL kernel.

    # reboot

  6. Remove third-party packages from the original OS that remained unchanged (typically packages that do not have a RHEL counterpart). To get a list of such packages, use:

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

    Replace RHEL_RepoID with the repository ID.

  7. If necessary, reconfigure system services after the conversion.

Troubleshooting

Logs

The Convert2RHEL utility stores the convert2rhel.log file in the /var/log/convert2rhel/ directory. Its content is identical to what is printed to the standard output.

The output of the rpm -Va command, which is run automatically unless the --no-rpm-va option is used, is stored in the /var/log/convert2rhel/rpm_va.log file for debugging purposes.

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, 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 are needed. Please contact Red Hat Consulting services for help.

Known issues

  • The conversion stops if any files are mounted directly to the /mnt/ directory or if the /sys/ directory is mounted as read-only.
  • Systems using high availability cluster software by Red Hat or third parties are not currently supported for conversion to RHEL. Red Hat recommends migrating to newly installed RHEL systems to ensure the integrity of these environments.
  • Systems using kernel modules that do not exist in RHEL kernel modules are not currently supported for conversion. Unsupported kernel modules include:
    • Kernel modules for specialized applications, GPUs, network drivers, or storage drivers
    • Custom compiled kernel modules built by DKMS
      Red Hat recommends disabling or uninstalling foreign kernel modules before the conversion and then enabling or reinstalling those kernel modules afterwards.

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

      • 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

      • Install a repository file for the client-tools repository that contains the subscription-manager package:

        • For conversions to RHEL 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 conversions to RHEL 8:
        curl -o /etc/yum.repos.d/client-tools.repo https://ftp.redhat.com/redhat/client-tools/client-tools-for-rhel-8-server.repo
        • For conversions to RHEL 9:
        curl -o /etc/yum.repos.d/client-tools.repo https://ftp.redhat.com/redhat/client-tools/client-tools-for-rhel-9.repo

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

    1. Remove the organization ID and activation key from the /etc/convert2rhel.ini file.

    2. Perform the conversion to RHEL:

    # convert2rhel

(BZ#1965487)

  • If you are registered to RHSM and are using RHSM credentials to convert, the system is re-registered and the original RHSM registration is not restored if a rollback is performed during the conversion. To work around this issue, register your system again with RHSM after the rollback.

Obtaining support

IMPORTANT:
Conversions from Scientific Linux 7 to RHEL 7 are not currently supported by Red Hat. Conversions from Alma Linux, CentOS Linux, Oracle Linux, or Rocky Linux to RHEL are supported by Red Hat. For more information on supported conversions, see Converting from a Linux distribution to RHEL using the Convert2RHEL utility.

To report a bug in Convert2RHEL, file an issue in GitHub.

Additional resources

Converting from a Linux distribution to RHEL using the Convert2RHEL utility
Red Hat Enterprise Linux technology capabilities and limits
Red Hat Enterprise Linux documentation
Migration planning guide - migration to RHEL 7
Considerations in adopting RHEL 8
Upgrading from RHEL 7 to RHEL 8
How to create a local mirror of the latest update for Red Hat Enterprise Linux 5, 6, 7, 8 without using Satellite server?
Blog post: Converting from CentOS to RHEL with Convert2RHEL and Satellite

Comments