Converting from an RPM-based Linux distribution to RHEL

Red Hat Enterprise Linux 8

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

Red Hat Customer Content Services

Abstract

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

Preface

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

Note

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:

    1. 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.
    2. Use your mouse cursor to highlight the part of text that you want to comment on.
    3. Click the Add Feedback pop-up that appears below the highlighted text.
    4. Follow the displayed instructions.
  • For submitting more complex feedback, create a Bugzilla ticket:

    1. Go to the Bugzilla website.
    2. As the Component, use Documentation.
    3. Fill in the Description field with your suggestion for improvement. Include a link to the relevant part(s) of documentation.
    4. 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).

Update

Sometimes called a software patch, an update is an addition to the current version of the application, operating system, or software that you are running. A software update addresses any issues or bugs to provide a better experience of working with the technology. In RHEL, an update relates to a minor release, for example, updating from RHEL 8.1 to 8.2.

Upgrade

An upgrade is when you replace the application, operating system, or software that you are currently running with a newer version. Typically, you first back up your data according to instructions from Red Hat. When you upgrade RHEL, you have two options:

  • In-place upgrade: During an in-place upgrade, you replace the earlier version with the new version without removing the earlier version first. The installed applications and utilities, along with the configurations and preferences, are incorporated into the new version.
  • Clean install: A clean install removes all traces of the previously installed operating system, system data, configurations, and applications and installs the latest version of the operating system. A clean install is ideal if you do not need any of the previous data or applications on your systems or if you are developing a new project that does not rely on prior builds.

Operating system conversion

A conversion is when you convert your operating system from a different Linux distribution to Red Hat Enterprise Linux. Typically, you first back up your data according to instructions from Red Hat.

Migration

Typically, a migration indicates a change of platform: software or hardware. Moving from Windows to Linux is a migration. Moving a user from one laptop to another or a company from one server to another is a migration. However, most migrations also involve upgrades, and sometimes the terms are used interchangeably.

  • Migration to RHEL: Conversion of an existing operating system to RHEL
  • Migration across RHEL: Upgrade from one version of RHEL to another

Chapter 1. Supported conversion paths

Important

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

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 OSTarget OSArchitectureProduct Variant

CentOS Linux 8.4

RHEL 8.4

64-bit Intel

N/A

CentOS Linux 7.9

RHEL 7.9

64-bit Intel

Server

Oracle Linux 8.4

RHEL 8.4

64-bit Intel

N/A

Oracle Linux 7.9

RHEL 7.9

64-bit Intel

Server

Important

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

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.

Procedure

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

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

  4. Install Convert2RHEL:

    1. Download the Red Hat GPG key:

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

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

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

    3. Install the Convert2RHEL utility:

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

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

      Note

      Ensure that the Satellite server meets the following conditions:

      • Satellite has a subscription manifest with RHEL repositories imported. For more information, see the Managing Subscriptions chapter in the Content Management Guide for the particular version of Red Hat Satellite, for example, for version 6.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
    3. 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 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.

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

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

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

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

Prerequisites

Procedure

  1. Start the Convert2RHEL utility.

    You can use Convert2RHEL with either RHSM or custom repositories.

    • Using RHSM:

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

      • 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 --pool option 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, rhel-7-server-rpms or rhel-8-baseos and rhel-8-appstream.

      To display all available options, use the -h, --help option:

      # convert2rhel -h
      Note

      When converting using RHSM or custom repositories, you can enable the RHEL 7 Extras or Optional repositories manually 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.

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

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

The 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 Convert2RHEL starts replacing packages from the original distribution with RHEL packages can be reverted. This moment is indicated by the warning message:

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

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

    Note

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

  • 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, Convert2RHEL is unable to restore the system to the original state even if the tool execution is stopped in the early stages of the conversion because Convert2RHEL removes 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 yum update command before starting the conversion process.
Warning

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.

Console Output

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

Logs

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

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.

Prerequisites

Procedure

  1. Identify dependencies errors:

    # yum check dependencies

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

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

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:

    1. Configure yum to use an HTTP proxy as described in How to enable Proxy settings for Yum Command on RHEL?
    2. For Oracle Linux conversions, define and enable repositories pointing to the following URLs:

    3. Install the subscription-manager package.
    4. Configure HTTP proxy for RHSM as described in How to configure HTTP Proxy for Red Hat Subscription Management.
    5. Prevent the configuration file from being deleted during the conversion:

      chattr +i /etc/rhsm/rhsm.conf
    6. Perform the conversion to RHEL.

      (BZ#1965487)

  • RHEL 8 systems with the python39-psycopg2-debug package installed encounter dependency issues during the conversion, resulting in a broken RHEL system. To work around the problem, remove the python39-psycopg2-debug package 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 sosreport from your system.
    • Generate an sosreport directly on your system:

      # sosreport

      Note that you can leave the case ID empty.

  • Submit a bug report:

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

For details on generating an sosreport, see the solution What is an sosreport and how to create one in Red Hat Enterprise Linux?.

For more information 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.

Chapter 6. Additional resources

Legal Notice

Copyright © 2021 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.