Chapter 8. Troubleshooting

You can refer to the following tips to troubleshoot upgrading from RHEL 7 to RHEL 8.

8.1. Troubleshooting resources

You can refer to the following troubleshooting resources.

Console output

By default, only error and critical log level messages are printed to the console output by the Leapp utility. To change the log level, use the --verbose or --debug options with the leapp upgrade command.

  • In verbose mode, Leapp prints info, warning, error, and critical messages.
  • In debug mode, Leapp prints debug, info, warning, error, and critical messages.

Logs

  • The /var/log/leapp/leapp-upgrade.log file lists issues found during the initramfs phase.
  • The /var/log/leapp/dnf-debugdata/ directory contains transaction debug data. This directory is present only if the leapp upgrade command is executed with the --debug option.
  • The /var/log/leapp/answerfile contains questions required to be answered by Leapp.
  • The journalctl utility provides complete logs.

Reports

8.2. Troubleshooting tips

You can refer to the following troubleshooting tips.

Pre-upgrade phase

  • Verify that your system meets all conditions listed in Planning an upgrade.
  • Make sure you have followed all steps described in Preparing a RHEL 7 system for the upgrade for example, your system does not use more than one Network Interface Card (NIC) with a name based on the prefix used by the kernel (eth).
  • Make sure you have answered all questions required by Leapp in the /var/log/leapp/answerfile file. If any answers are missing, Leapp inhibits the upgrade. Example questions:

    • Disable pam_pkcs11 module in PAM configuration?
    • Disable pam_krb5 module in PAM configuration?
    • Configure PAM and nsswitch.conf with the following authselect call?
  • Make sure you have resolved all problems identified in the pre-upgrade report, located at /var/log/leapp/leapp-report.txt. To achieve this, you can also use the web console, as described in Assessing upgradability and applying automated remediations through the web console.

Example 8.1. Leapp answerfile

The following is an example of an unedited /var/log/leapp/answerfile file that has one unanswered question:

[remove_pam_pkcs11_module_check]
# Title:          	None
# Reason:         	Confirmation
# =================== remove_pam_pkcs11_module_check.confirm ==================
# Label:          	Disable pam_pkcs11 module in PAM configuration? If no, the upgrade process will be interrupted.
# Description:    	PAM module pam_pkcs11 is no longer available in RHEL-8 since it was replaced by SSSD.
# Type:           	bool
# Default:        	None
# Available choices: True/False
# Unanswered question. Uncomment the following line with your answer
# confirm =

The Label field specifies the question that requires an answer. In this example, the question is Disable pam_pkcs11 module in PAM configuration?

To answer the question, uncomment the confirm line and enter an answer of True or False. In this example, the selected answer is True:

[remove_pam_pkcs11_module_check]
...
# Available choices: True/False
# Unanswered question. Uncomment the following line with your answer
confirm = True

Download phase

  • If a problem occurs during downloading RPM packages, examine transaction debug data located in the /var/log/leapp/dnf-debugdata/ directory.

initramfs phase

  • During this phase, potential failures redirect you to the Dracut shell. Check the Journal log:

    # journalctl

    Alternatively, restart the system from the Dracut shell using the reboot command and check the /var/log/leapp/leapp-upgrade.log file.

Post-upgrade phase

  • If your system seems to be successfully upgraded but booted with the old RHEL 7 kernel, restart the system and check the kernel version of the default entry in GRUB.
  • Make sure you have followed the recommended steps in Verifying the post-upgrade state of the RHEL 8 system.
  • If your application or a service stops working or behaves incorrectly after you have switched SELinux to enforcing mode, search for denials using the ausearch, journalctl, or dmesg utilities:

    # ausearch -m AVC,USER_AVC -ts boot
    # journalctl -t setroubleshoot
    # dmesg | grep -i -e selinux -e type=1400

    The most common problems are caused by incorrect labeling. See Troubleshooting problems related to SELinux for more details.

8.3. Known issues

The following are Known Issues you may encounter when upgrading from RHEL 7 to RHEL 8.

  • Network teaming currently does not work when the in-place upgrade is performed while Network Manager is disabled or not installed.
  • If you use an HTTP proxy, Red Hat Subscription Manager must be configured to use such a proxy, or the subscription-manager command must be executed with the --proxy <hostname> option. Otherwise, an execution of the subscription-manager command fails. If you use the --proxy option instead of the configuration change, the upgrade process fails because Leapp is unable to detect the proxy. To prevent this problem from occurring, manually edit the rhsm.conf file as described in How to configure HTTP Proxy for Red Hat Subscription Management. (BZ#1689294)
  • If your RHEL 7 system is installed on an FCoE Logical Unit Number (LUN) and connected to a network card that uses the bnx2fc driver, the LUN is not detected in RHEL 8 after the upgrade. Consequently, the upgraded system fails to boot. (BZ#1718147)
  • If your RHEL 7 system uses a device driver that is provided by Red Hat but is not available in RHEL 8, Leapp inhibits the upgrade. However, if the RHEL 7 system uses a third-party device driver that is not included in the list of removed drivers (located at /etc/leapp/repos.d/system_upgrade/el7toel8/actors/kernel/checkkerneldrivers/files/removed_drivers.txt), Leapp does not detect such a driver and proceeds with the upgrade. Consequently, the system might fail to boot after the upgrade.
  • You cannot perform an in-place upgrade when the winbind and wins Samba modules are used in the /etc/nsswitch.conf file at the moment. The upgrade transaction fails with the following error messages and Leapp inhibits the upgrade:

    upgrade[469]: STDERR:
    upgrade[469]: Error in PREIN scriptlet in rpm package unbound-libs
    upgrade[469]: Error: Transaction failed
    upgrade[469]: Container el8userspace failed with error code 1.
    unbound-libs has a PREIN failure

    To work around this problem, configure the system so that it uses only local providers for the user, groups, and hosts database during the update:

    1. Open the system /etc/nsswitch.conf configuration file and search for entries that contain the winbind or wins strings.
    2. If you find such entries, create a backup of /etc/nsswitch.conf.
    3. Edit /etc/nsswitch.conf and remove winbind or wins from the entries that contain them.
    4. Perform an in-place upgrade.
    5. After the upgrade, add the winbind and wins strings to the respective entries in /etc/nsswitch.conf, based on your system configuration requirements.

      (BZ#1410154)

  • The Leapp utility does not change customized authentication configuration during the upgrade process. If you used the deprecated authconfig utility to configure authentication on your RHEL 7 system, authentication on RHEL 8 might not work correctly. To ensure that your custom configuration functions properly on the RHEL 8 system, re-configure your RHEL 8 system with the authselect utility.

    Important

    During the in-place upgrade, the deprecated pam_krb5 or pam_pkcs11 pluggable authentication modules (PAM) are removed. Consequently, if the PAM configuration on your RHEL 7 system contains the pam_krb5 or pam_pkcs11 modules and if these modules have the required or requisite control values, performing the in-place upgrade might result in locking you out of the system. To work around this problem, reconfigure your RHEL 7 system to not use pam_krb5 or pam_pkcs11 before you start the upgrade process.

  • On IBM Z systems, Leapp always expects a DASD disk attached. Consequently, if the /etc/dasd.conf file does not exist, the in-place upgrade fails. To work around this problem, create an empty dasd.conf file by using the touch > /etc/dasd.conf command. (BZ#1783248)
  • If a name of a third-party package (not signed by Red Hat) installed on your system is the same as of a package provided by Red Hat, the in-place upgrade fails. To work around this problem, choose one of the following options prior to upgrading:

    1. Remove the third-party package
    2. Replace the third-party package with the package provided by Red Hat
  • During an in-place upgrade, the docker package is removed without a warning. If you use containers in RHEL, migrate to Podman prior to upgrading to RHEL 8. For instructions, see How do I migrate my Docker containers to Podman prior to moving from Red Hat Enterprise Linux 7 to Red Hat Enterprise Linux 8?. (BZ#1858711)
  • Due to security reasons, support for single-DES (DES) and triple-DES (3DES) encryption types has been removed from RHEL 8.3.0. RHEL 7 Identity Management (IdM), however, still supports 3DES encryption.
    Upgrading an IdM environment from RHEL 7 to RHEL 8 is possible because both versions of RHEL prefer stronger AES encryption types by default:

    Version of IdMDefault encryption typesAdditional supported encryption types

    RHEL 7

    aes256-cts
    aes128-cts

    camellia256-cts
    camellia128-cts
    des3-hmac
    arcfour-hmac

    RHEL 8

    aes256-cts
    aes128-cts

    aes256-sha2
    aes128-sha2
    camellia256-cts
    camellia128-cts
    arcfour-hmac [a]

    [a] RC4 encryption has been deprecated and disabled by default in RHEL 8, as it is considered less secure than the newer AES-128 and AES-256 encryption types. For more information on enabling RC4 support for compatibility with legacy Active Directory environments, see Ensuring support for common encryption types in AD and RHEL.

    If you manually configured a non-IdM Kerberos Distribution Center (KDC), any services, or any users to only use DES or 3DES encryption, you might experience service interruptions after updating to the latest Kerberos packages in RHEL 8, such as:

    • Kerberos authentication errors
    • unknown enctype encryption errors
    • KDCs with DES-encrypted Database Master Keys (K/M) fail to start

    Red Hat recommends you do not use DES or 3DES encryption in your environment. For more information on re-keying Kerberos principals to use stronger encryption types, see Retiring DES from MIT Kerberos Documentation.

8.4. Obtaining support

You can open a support case, select RHEL 8 as the product, and provide a sosreport from your system.

  • To generate a sosreport on your system, run:
# sosreport

Note that you can leave the case ID empty.

For details on generating a 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?.