Converting from a Linux distribution to RHEL using the Convert2RHEL utility

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. 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. If converting from CentOS Linux, 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 7 and CentOS Linux 8 have reached end of life. For more information, see CentOS Linux EOL.

5. Install Convert2RHEL:

   1. Download the Red Hat GPG key:

      # curl -o /etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release https://security.access.redhat.com/data/fd431d51.txt

   2. Install the Convert2RHEL repository file.

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

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

         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

6. 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 Red Hat Subscriptions chapter in the Managing Content guide for the particular version of Red Hat Satellite, for example, for version 6.14.

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

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

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

9. Temporarily disable antivirus software to prevent the conversion from failing.
10. If you are accessing RHEL packages by using custom repositories, disable these repositories. The Convert2RHEL utility enables the custom repositories during the conversion process.

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

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

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 the --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.
   • 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 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. Optional: Remove any remaining Convert2RHEL packages, files, and repositories:

   1. Remove the Convert2RHEL package:

      # yum remove -y convert2rhel

   2. Remove Convert2RHEL files and repositories:

      # rm -f /etc/convert2rhel.ini.rpmsave
      # rm -f /etc/yum.repos.d/convert2rhel.repo

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

8. If you have converted a system in Amazon Web Services (AWS) or Microsoft Azure with the Red Hat Enterprise Linux for Third Party Linux Migration with ELS offering, enable host metering on the system. For more information, see Enabling metering for Red Hat Enterprise Linux with Extended Lifecycle Support in your cloud environment.
9. 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.

Procedure

1. Back up your systems and verify that they 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 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.

4. If you are converting with a firewall or through a proxy server, ensure that you have access to the following connections:

   • https://cdn-ubi.redhat.com
   • 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

5. 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://security.access.redhat.com/data/fd431d51.txt

   2. Install the client-tools repository file:

      # curl -o /etc/yum.repos.d/client-tools.repo https://cdn-public.redhat.com/content/public/repofiles/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

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

Procedure

1. Log in to the Red Hat Hybrid Cloud Console and go to Red Hat Enterprise Linux > Insights for RHEL > Automation toolkit > Tasks.
2. Locate the Pre-conversion analysis for converting to RHEL task and click Select systems.
3. Alternatively, log in to the Red Hat Hybrid Cloud Console, go to Red Hat Enterprise Linux > Insights for RHEL > Inventory > Systems, choose a system you want to convert and click Convert system to RHEL label.
4. In the Task name field type the name of the task and select the CentOS Linux 7 systems that you want to analyze for conversion. Click Next.

5. Configure the pre-conversion analysis task with the following settings:

   Do not use the ELS subscription

   Choose this option if you plan to upgrade your RHEL system to version 8 or higher.

   Allow kernel modules outside of RHEL repositories on the system

   Choose this option to allow the pre-conversion analysis to ignore kernel modules that are not part of RHEL repositories.

   Allow outdated kernel on the system

   Choose this option to allow the pre-conversion analysis to ignore when your system is booted from an outdated kernel.

   Allow outdated packages on the system

   Choose this option to allow the pre-conversion analysis to ignore all outdated packages on the system.

6. Click Run task. 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

   

   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. You must resolve this issue before converting.
   • Overridable inhibitor: Would cause the conversion to fail because it is very likely to result in a deteriorated system state. You must resolve or manually override this issue before converting. For more details about which inhibitors you can override, see the step about configuring the settings of the pre-conversion analysis in this procedure.
   • 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.
7. 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.

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:

     • You have completed all steps in Preparing for a RHEL conversion using Insights.
     • The system contains all packages required for the conversion.
     • The system is running.
     • You have resolved all issues found in the Reviewing the pre-conversion analysis report using Insights.

   • 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

     

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.

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.