Converting from an RPM-based Linux distribution to RHEL using Red Hat Insights

Red Hat Insights 1-latest

Instructions for a conversion from CentOS Linux 7 to Red Hat Enterprise Linux 7 using Red Hat Insights

Red Hat Customer Content Services

Abstract

This document provides instructions on how to convert your operating system from CentOS Linux to RHEL 7 using Red Hat Insights.

Preface

This document provides instructions on how to convert your operating system from CentOS Linux to Red Hat Enterprise Linux (RHEL) 7 using Red Hat Insights.

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 feedback on our documentation. Let us know how we can improve it.

Submitting feedback through Jira (account required)

  1. Log in to the Jira website.
  2. Click Create in the top navigation bar.
  3. Enter a descriptive title in the Summary field.
  4. Enter your suggestion for improvement in the Description field. Include links to the relevant parts of the documentation.
  5. 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

Important

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.

Table 1.1. Supported conversion paths

Source OSSource versionTarget OS and versionProduct VariantAvailable Conversion Methods

Alma Linux

8.9

RHEL 8.9

N/A

Command-line interface, Satellite

8.8

RHEL 8.8 EUS

N/A

Command-line interface, Satellite

8.6

RHEL 8.6 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.9

RHEL 8.9

N/A

Command-line interface, Satellite

7.9

RHEL 7.9

Server

Command-line interface, Satellite

Rocky Linux

8.9

RHEL 8.9

N/A

Command-line interface, Satellite

8.8

RHEL 8.8 EUS

N/A

Command-line interface, Satellite

8.6

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

In addition to the above supported conversion paths, it is also possible to perform an unsupported conversion from Scientific Linux to RHEL. For information about unsupported conversions, see How to perform an unsupported conversion from a RHEL-derived Linux distribution to RHEL.

Important

Conversions from CentOS Stream to RHEL are not currently possible.

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.

    Note

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

    Note

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

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.

Note

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 of both CentOS Linux and Oracle Linux.

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

Chapter 4. Preparing for a RHEL conversion using Insights

Before running the pre-conversion analysis by using Red Hat Insights and performing the conversion, you must first complete all necessary preparation steps.

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 an sosreport 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

  1. Ensure that you have a RHEL subscription. You can obtain a subscription using one of the following methods:

    1. Get a no-cost RHEL Developer Subscription for Individuals. The Developer Subscription is limited to sixteen servers.
    2. Start a 60-day free trial for a RHEL subscription. You can cancel this trial at any time.
    3. Contact the Red Hat Sales team for assistance. If you plan to convert a large number of servers, Red Hat recommends coordinating with the Sales team.
  2. Back up your systems and verify that they can be restored if needed.
  3. Check Known issues and limitations and verify that your system is supported for conversion. Apply workarounds where applicable.
  4. 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.
  5. If you are converting with a firewall or through a proxy server, ensure that you have access to the following connections:

  6. 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://www.redhat.com/security/data/fd431d51.txt
    2. Install the client-tools repository file:

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

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.

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

Procedure

  1. Log in to the Red Hat Hybrid Cloud Console and go to Red Hat Insights > RHEL > Automation toolkit > Tasks.
  2. Locate the Pre-conversion analysis for converting to RHEL task and click Run task.
  3. Select the CentOS Linux 7 systems that you want to analyze for conversion and click Execute task.

    Note

    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

    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. This issue must be resolved before converting.
    • 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.
  4. 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.

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

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:

    • If the conversion timed out without completing, verify that the system is running and retry at another time. If issues persist, contact Support.

      Figure 6.1. Convert to RHEL from CentOS 7 Linux

      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.

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 the rpm -Va command, which is run automatically unless the --no-rpm-va option is used with the convert2rhel 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

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.

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

  1. Log in to the Red Hat Hybrid Cloud Console and go to Red Hat Insights > RHEL > Inventory > Systems.
  2. Select the affected system from the table.
  3. In the General Information tab, go to the System Status card and verify the RHC status:

    1. If the RHC status is Connected, RHC is connected correctly.
    2. If the RHC status is Not available, RHC is disconnected. Proceed to the next step to reconnect RHC.
  4. Unregister the system in your terminal:

    # rhc disconnect
  5. To help with troubleshooting, set the RHC systemd service (rhcd) logging to the highest level:

    # sed -ie 's%error%trace%' /etc/rhc/config.toml
  6. 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 the insights-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

  1. Verify if the affected system is unavailable, for example because of a network accessibility issue or because the system is shut off.
  2. Review the RHC systemd service (rhcd) for errors:

    1. Stop rhcd in your terminal:

      # systemctl stop rhcd
    2. Set rhcd logging to the highest level:

      # sed -ie 's%error%trace%' /etc/rhc/config.toml
    3. Restart rhcd:

      # systemctl start rhcd
    4. Review error messages posted by rhcd:

      # journalctl -u rhcd
  3. 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. (RHELC-559)
  • UEFI systems with Secure Boot enabled are not supported for conversion. To work around this issue, disable Secure Boot before the conversion and then re-enable after the conversion is complete. (RHELC-138)
  • 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)
  • Some inhibitors found in the pre-conversion analysis and conversion can be overridden by setting an environment variable. Due to a known issue, the Hybrid Cloud Console does not recognize when this environment variable is set. As a result, overridable inhibitors must be remediated when converting by using Insights. (RHINENG-5943)

7.5. Obtaining support

If you experience problems during the conversion, notify Red Hat so that these problems can be addressed.

Important

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

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

Legal Notice

Copyright © 2024 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.