Chapter 5. Troubleshooting conversions

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)

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.