Converting from a Linux distribution to RHEL using the Convert2RHEL utility
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 using the Convert2RHEL utility
Abstract
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.
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.
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)
- Log in to the Jira website.
- Click Create in the top navigation bar.
- Enter a descriptive title in the Summary field.
- Enter your suggestion for improvement in the Description field. Include links to the relevant parts of the documentation.
- 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
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.
Source OS | Source version | Target OS and version | Product Variant | Available Conversion Methods |
---|---|---|---|---|
Alma Linux | 8.10 | RHEL 8.10 | N/A | Command-line interface, Satellite |
8.8 | RHEL 8.8 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.10 | RHEL 8.10 | N/A | Command-line interface, Satellite |
7.9 | RHEL 7.9 | Server | Command-line interface, Satellite | |
Rocky Linux | 8.10 | RHEL 8.10 | N/A | Command-line interface, Satellite |
8.8 | RHEL 8.8 EUS | N/A | Command-line interface, Satellite |
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.
RHEL 7 reaches the end of the Maintenance Support Phase on June 30, 2024. 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. Note that without ELS, you have limited support for RHEL 7, including for the upgrade from RHEL 7 to RHEL 8. For more information, see the Red Hat Enterprise Linux Life Cycle and the Convert2RHEL Support Policy.
In addition to the above supported conversion paths, it is also possible to perform an unsupported conversion from Scientific Linux 7 and CentOS Stream 8 to RHEL. For information about unsupported conversions, see How to perform an unsupported conversion from a RHEL-derived Linux distribution to RHEL.
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.
NoteIf 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 Red Hat 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.
NoteInsights supports conversions with Red Hat Enterprise Linux for Third Party Migration with the pay-as-you-go pricing model on Amazon Web Services (AWS). For more information, see Red Hat Enterprise Linux for Third Party Linux Migration.
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.
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.
- 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.
- Foreman - Conversions of systems that use Foreman with the Katello plugin are not supported. To perform a supported conversion, migrate to Red Hat Satellite first and then proceed with the conversion.
-
RAID - It is not possible to convert UEFI-based systems with
mdadm
-managed RAID devices.
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 ansosreport
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.
- You have enabled Simple Content Access (SCA). Red Hat accounts created after July 15, 2022 have SCA enabled by default.
Procedure
- Back up your system and verify that it can be restored if needed.
- Check Known issues and limitations and verify that your system is supported for conversion. Apply workarounds where applicable.
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
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-*
ImportantCentOS Linux 7 and CentOS Linux 8 have reached end of life. For more information, see CentOS Linux EOL.
Install
Convert2RHEL
: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
NoteYou 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
Ensure you have 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 corresponding minor version of RHEL per Table 1.1.
Red Hat Satellite in a version that has Full or Maintenance support. For more information, see Red Hat Satellite Product Life Cycle.
NoteEnsure 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 and8.9
,8.8
, or8.6
for Alma Linux, Oracle Linux, or Rocky Linux conversions.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.NoteRHEL 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.
- 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.
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.
- Temporarily disable antivirus software to prevent the conversion from failing.
-
If you are accessing RHEL packages by using custom repositories, disable these repositories. The
Convert2RHEL
utility enables the custom repositories during the conversion process. 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.
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
- You have completed the steps listed in Preparing for a RHEL conversion.
Procedure
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.
-
If you are converting to RHEL 8.8 and have an Extended Upgrade Support (EUS), add the
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]
- 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).
Procedure
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
orrhel-8-baseos
andrhel-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.
-
To display all available options, use the
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.-
Wait until
Convert2RHEL
installs the RHEL packages and finishes successfully. - 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?.
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
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.
- 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.
- 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
Prepare your system for the pre-conversion analysis by using Red Hat Insights and then performing the conversion to RHEL with the steps below.
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 ansosreport
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
- Back up your systems and verify that they can be restored if needed.
- Check Known issues and limitations and verify that your system is supported for conversion. Apply workarounds where applicable.
- 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.
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
Install the Red Hat client tools:
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
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
Install the
client tools
packages:# yum -y install subscription-manager subscription-manager-rhsm-certificates rhc rhc-worker-script insights-client
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
- Log in to the Red Hat Hybrid Cloud Console and go to Red Hat Insights > RHEL > Inventory > Systems.
- Verify that your CentOS Linux systems appear as expected.
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
- You have completed the steps listed in Preparing for a RHEL conversion using Insights.
Procedure
- Log in to the Red Hat Hybrid Cloud Console and go to Red Hat Enterprise Linux > Insights for RHEL > Automation toolkit > Tasks.
- Locate the Pre-conversion analysis for converting to RHEL task and click .
- 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.
- 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 .
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.
Click
. 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.
- 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
You have completed the steps listed in Preparing for a RHEL conversion using Insights and Reviewing the pre-conversion analysis report using Insights.
NoteTo avoid serious problems after the conversion, do not convert any systems that have unresolved inhibitors and warnings in the pre-conversion analysis.
Procedure
- Log in to the Red Hat Hybrid Cloud Console and go to Red Hat Insights > RHEL > Automation toolkit > Tasks.
- Locate the Convert to RHEL from CentOS 7 Linux task and click Run task.
Select the CentOS Linux 7 systems that you want to convert to RHEL and click Execute task.
NoteThe conversion process can take up to an hour to complete.
- Go to the Activity tab and select the newly generated conversion report.
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
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.
- 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.
NoteIf the
-y
option is used with theconvert2rhel
command, the question indicating the moment after which the automated rollback is no longer possible is skipped.
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 therpm -Va
command, which is run automatically unless the--no-rpm-va
option is used with theconvert2rhel
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
- You have successfully completed the conversion to RHEL. See Converting to a RHEL system for more information.
Procedure
Identify dependencies errors:
# yum check dependencies
If the command displays no output, no further actions are required.
-
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
- Log in to the Red Hat Hybrid Cloud Console and go to Red Hat Insights > RHEL > Inventory > Systems.
- Select the affected system from the table.
In the General Information tab, go to the System Status card and verify the RHC status:
- If the RHC status is Connected, RHC is connected correctly.
- If the RHC status is Not available, RHC is disconnected. Proceed to the next step to reconnect RHC.
Unregister the system in your terminal:
# rhc disconnect
To help with troubleshooting, set the
RHC systemd
service (rhcd
) logging to the highest level:# sed -ie 's%error%trace%' /etc/rhc/config.toml
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 theinsights-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
- Verify if the affected system is unavailable, for example because of a network accessibility issue or because the system is shut off.
Review the
RHC systemd
service (rhcd
) for errors:Stop rhcd in your terminal:
# systemctl stop rhcd
Set
rhcd
logging to the highest level:# sed -ie 's%error%trace%' /etc/rhc/config.toml
Restart
rhcd
:# systemctl start rhcd
Review error messages posted by
rhcd
:# journalctl -u rhcd
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 using the command-line interface. To work around this problem, enable HTTP proxy for yum and then configure the HTTP proxy for RHSM:
- Configure yum to use an HTTP proxy as described in How to enable proxy settings for yum command on RHEL?
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 thesubscription-manager
package:conversions to RHEL 7:
# curl -o /etc/yum.repos.d/client-tools.repo https://cdn-public.redhat.com/content/public/repofiles/client-tools-for-rhel-7-server.repo
For conversions to RHEL 8:
# curl -o /etc/yum.repos.d/client-tools.repo https://cdn-public.redhat.com/content/public/repofiles/client-tools-for-rhel-8.repo
If you are converting to an earlier version of RHEL 8, for example, RHEL 8.5, update the
$releasever
value in the client-tools repository:# sed -i 's%\$releasever%<release_version>%' /etc/yum.repos.d/client-tools.repo
Replace release_version with the correct release version, for example
8.5
or8.8
.Install the following subscription-manager packages:
# yum -y install subscription-manager subscription-manager-rhsm-certificates
- Configure HTTP proxy for RHSM as described in How to configure HTTP Proxy for Red Hat Subscription Management.
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.
-
Remove the organization ID and activation key from the
/etc/convert2rhel.ini
file. Perform the conversion to RHEL:
# convert2rhel
UEFI systems with Secure Boot enabled are not supported for conversion. To work around this issue, complete the following steps:
- Disable Secure Boot before the conversion.
If converting from Oracle Linux 7 or Alma Linux 8, reinstall the
shim-x64
package:# yum reinstall -y shim-x64
Re-enable after the conversion is complete.
- 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)
7.5. Obtaining support
If you experience problems during the conversion, notify Red Hat so that these problems can be addressed.
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 ansosreport
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.
-
Select RHEL 7 or RHEL 8 as the product, and provide an
Submit a bug report:
-
Open a bug, select RHEL 7 or RHEL 8 as the product, and select
convert2rhel
as the component.
-
Open a bug, select RHEL 7 or RHEL 8 as the product, and select
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
- How to perform an unsupported conversion from a RHEL-derived Linux distribution to RHEL
- 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
- Convert2RHEL FAQ (Frequently Asked Questions)