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.