SupportConsoleDevelopersStart a trialContact

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 using the command-line interface. 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. Install the subscription-manager package:

      1. Download the Red Hat GPG key: 

        # curl -o /etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release https://security.access.redhat.com/data/fd431d51.txt

      2. Install a repository file for the client-tools repository that contains the subscription-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

      3. 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 or 8.8.

      4. Install the following subscription-manager packages: 

        # yum -y install subscription-manager subscription-manager-rhsm-certificates
    3. Configure HTTP proxy for RHSM as described in How to configure HTTP Proxy for Red Hat Subscription Management.

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

    5. Remove the organization ID and activation key from the /etc/convert2rhel.ini file.

    6. Perform the conversion to RHEL: 

      # convert2rhel

      (RHELC-559)

  • UEFI systems with Secure Boot enabled are not supported for conversion. To work around this issue, complete the following steps:

    1. Disable Secure Boot before the conversion.

    2. If converting from Oracle Linux 7 or Alma Linux 8, reinstall the shim-x64 package: 

      # yum reinstall -y shim-x64

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

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.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.