Converting from an RPM-based Linux distribution to RHEL
Instructions for a conversion from CentOS Linux or Oracle Linux to Red Hat Enterprise Linux 7 and Red Hat Enterprise Linux 8
This document provides instructions on how to convert your operating system from a different Linux distribution, namely CentOS Linux or Oracle Linux, to Red Hat Enterprise Linux (RHEL) 7 or RHEL 8. The conversion is performed by the
The conversion from CentOS Linux 6 or Oracle Linux 6 to RHEL 6 is not currently supported by Red Hat. For information on an unsupported conversion, see How to convert from CentOS Linux 6 or Oracle Linux 6 to RHEL 6.
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 input on our documentation. Please let us know how we could make it better. To do so:
For simple comments on specific passages:
- Make sure you are viewing the documentation in the Multi-page HTML format. In addition, ensure you see the Feedback button in the upper right corner of the document.
- Use your mouse cursor to highlight the part of text that you want to comment on.
- Click the Add Feedback pop-up that appears below the highlighted text.
- Follow the displayed instructions.
For submitting more complex feedback, create a Bugzilla ticket:
- Go to the Bugzilla website.
- As the Component, use Documentation.
- Fill in the Description field with your suggestion for improvement. Include a link to the relevant part(s) of documentation.
- Click Submit Bug.
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).
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.
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.
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.
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.
Currently, it is possible to convert your systems from the following Linux distributions, architectures, and versions to the corresponding minor version of RHEL listed in Table 1.1.
Table 1.1. Supported conversion paths
|Source OS||Target OS||Architecture||Product Variant|
CentOS Linux 8.4
CentOS Linux 7.9
Oracle Linux 8.4
Oracle Linux 7.9
Conversions from CentOS Stream to RHEL are not currently possible.
For information on Red Hat’s support policy for Linux distribution conversions, see Convert2RHEL Support Policy.
Chapter 2. Preparing for a RHEL conversion
This procedure describes the steps that are necessary before performing the conversion from CentOS Linux or Oracle Linux to Red Hat Enterprise Linux (RHEL).
- 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.
- Back up your system and verify that you can restore your system.
- Check Known issues and limitations and verify that your system is supported for conversion. Apply workarounds where applicable.
Ensure that the standard kernel is the booted kernel:
- CentOS Linux: the standard CentOS Linux kernel
Oracle Linux: the Red Hat Compatible Kernel (RHCK)
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.
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
# 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
# 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.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 RHEL 7.9 or RHEL 8.4 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 8.4
- Red Hat Enterprise Linux 8 for x86_64 - BaseOS RPMs 8.4
Custom repositories configured in the
/etc/yum.repos.d/directory and pointing to a mirror of the RHEL 7.9 or RHEL 8.4 repositories. Use custom repositories for systems that can connect to only local networks and cannot therefore 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
Convert2RHELutility, make sure to enable both repositories using the
--enablerepooption. 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, download the consumer RPM to the
# 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.
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 Rollback.
Chapter 3. Converting to a RHEL system
This procedure describes the steps necessary to convert your system from CentOS Linux or Oracle Linux to Red Hat Enterprise Linux (RHEL).
If you are accessing RHEL packages using Red Hat CDN or Satellite through RHSM, there are two methods of registering and subscribing your system during the conversion:
- Provide the organization ID and activation key. This method is preferred when converting many systems or when automating the conversion process using scripts. You must be the organization administrator to create an activation key. You must use this method if you are accessing RHEL packages using Satellite through RHSM.
- Provide the username, password, and pool ID. Any user who is accessing RHEL packages using Red Hat CDN through RHSM can use this method.
- You have completed the steps listed in Preparing for a RHEL conversion.
- If you are providing the organization ID and activation key to register and subscribe your system, you have created an activation key in Satellite or RHSM. For more information, see Managing activation keys in Satellite documentation and Understanding activation keys in RHSM documentation.
You can use
Convert2RHELwith either RHSM or custom repositories.
With the organization ID and activation key:
# convert2rhel --org organization_ID --activationkey activation_key
Replace organization_ID and activation_key with the organization ID and the 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.Note
If you are accessing RHEL packages using Satellite, you must use the organization ID and activation key to run the
With the username, password, and pool ID:
# convert2rhel --username username --password password --pool pool_ID
Replace username and password with your Red Hat Account credentials. Replace pool_ID with the pool ID of the subscription that you want to attach to the system. If you do not know the pool ID, omit the
--pooloption to generate a list of all subscriptions available for the account.
Using custom repositories:
# convert2rhel --no-rhsm --enablerepo RHEL_RepoID1 --enablerepo RHEL_RepoID2
Replace RHEL_RepoID with your custom repository configured in the
/etc/yum.repos.d/directory, for example,
To display all available options, use the
# convert2rhel -hNote
When converting using RHSM or custom repositories, you can enable the RHEL 7 Extras or Optional repositories manually by using the
--enablerepooption 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.
Convert2RHELstarts 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
Convert2RHELup to this point can be automatically reverted. Confirm that you wish to proceed with the conversion process.
Convert2RHELinstalls 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.
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 these packages, use:
# yum list extras --disablerepo="*" --enablerepo=RHEL_RepoID
Replace RHEL_RepoID with your repository.
- 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 4. Rollback
Convert2RHEL utility provides a limited rollback functionality. If the conversion is cancelled by the user or if it fails, the utility performs a rollback of changes made during the conversion process under the following conditions:
Only changes performed until
Convert2RHELstarts 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
-yoption is used with the
convert2RHELcommand, the question indicating the moment after which the automated rollback is no longer possible is skipped.
Access to repositories providing packages from the original distribution is required, especially to the base repository, to perform a rollback. Without access to these repositories,
Convert2RHELis unable to restore the system to the original state even if the tool execution is stopped in the early stages of the conversion because
Convert2RHELremoves certain packages during the conversion process and needs to preemptively download them from the original repository for rollback.
A rollback is feasible only on a system where all packages from the original OS are updated to the latest version that is available in the repositories accessible from the system. Therefore use the
yumupdate command before starting the conversion process.
If the conversion process is cancelled 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 5. Troubleshooting
This chapter lists troubleshooting resources and tips.
5.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.
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
/var/log/convert2rhel/convert2rhel.logfile lists debug, info, warning, error, and critical messages.
/var/log/convert2rhel/rpm_va.logfile lists all package files on the unconverted system that a user has modified. This output is generated by the
rpm -Vacommand, which is run automatically unless the
--no-rpm-vaoption is used with the
5.2. Fixing dependency errors
During a conversion from a different Linux distribution to RHEL, certain packages might be installed without some of their dependencies.
- You have successfully completed the conversion to RHEL. See Converting to a RHEL system for more information.
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
yumutility automatically installs missing dependencies. If the required dependencies are not provided by repositories available on the system, install those packages manually.
5.3. Known issues and limitations
The following issues and limitations are known to occur during the conversion:
- UEFI-based systems cannot currently be converted to RHEL. (BZ#1898314)
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. 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
- Systems in FIPS mode are not supported for conversion.
- RHEL packages cannot be accessed using Red Hat Update Infrastructure (RHUI) on public cloud instances. Use RHSM, Red Hat Satellite, or custom repositories instead.
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:
- Configure yum to use an HTTP proxy as described in How to enable Proxy settings for Yum Command on RHEL?
For Oracle Linux conversions, define and enable repositories pointing to the following URLs:
- Configure HTTP proxy for RHSM as described in How to configure HTTP Proxy for Red Hat Subscription Management.
Prevent the configuration file from being deleted during the conversion:
chattr +i /etc/rhsm/rhsm.conf
Perform the conversion to RHEL.
RHEL 8 systems with the
python39-psycopg2-debugpackage installed encounter dependency issues during the conversion, resulting in a broken RHEL system. To work around the problem, remove the
python39-psycopg2-debugpackage before the conversion.
5.4. Obtaining support
If you experience problems during the conversion, notify Red Hat so that these problems can be addressed. There are several methods for obtaining support.
Open a support case:
Select RHEL 7 or RHEL 8 as the product, and provide a
sosreportfrom your system.
sosreportdirectly on your system:
Note that you can leave the case ID empty.
- Select RHEL 7 or RHEL 8 as the product, and provide a
Submit a bug report:
Open a bug, select RHEL 7 or RHEL 8 as the product, and select
convert2rhelas 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 on 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 on Red Hat’s support policy for Linux distribution conversions, see Convert2RHEL Support Policy.