Chapter 9. Troubleshooting
You can refer to the following tips to troubleshoot upgrading from RHEL 7 to RHEL 8.
9.1. Troubleshooting resources
You can refer to the following troubleshooting resources.
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
--debug options with the
leapp upgrade command.
In verbose mode,
Leappprints info, warning, error, and critical messages.
In debug mode,
Leappprints debug, info, warning, error, and critical messages.
/var/log/leapp/leapp-upgrade.logfile lists issues found during the initramfs phase.
/var/log/leapp/dnf-debugdata/directory contains transaction debug data. This directory is present only if the
leapp upgradecommand is executed with the
/var/log/leapp/answerfilecontains questions required to be answered by
journalctlutility provides complete logs.
/var/log/leapp/leapp-report.txtfile lists issues found during the pre-upgrade phase. The report is also available in the web console, see Assessing upgradability and applying automated remediations through the web console.
/var/log/leapp/leapp-report.jsonfile lists issues found during the pre-upgrade phase in a machine-readable format, which enables you to process the report using custom scripts. For more information, see Automating your Red Hat Enterprise Linux pre-upgrade report workflow.
9.2. Troubleshooting tips
You can refer to the following troubleshooting tips.
- Verify that your system meets all conditions listed in Planning an upgrade.
Make sure you have followed all steps described in Preparing 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 (
Make sure you have answered all questions required by
/var/log/leapp/answerfilefile. If any answers are missing,
Leappinhibits 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 9.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 =
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
False. In this example, the selected answer is
[remove_pam_pkcs11_module_check] ... # Available choices: True/False # Unanswered question. Uncomment the following line with your answer confirm = True
If a problem occurs during downloading RPM packages, examine transaction debug data located in the
/var/log/leapp/dnf-debugdata/directory is empty or does not exist if no transaction debug data was produced. This might occur when the required repositories are not available.
During this phase, potential failures redirect you to the Dracut shell. Check the Journal log:
Alternatively, restart the system from the Dracut shell using the
rebootcommand and check the
- 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.
9.3. Known issues
The following are known issues you might 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-managercommand must be executed with the
--proxy <hostname>option. Otherwise, an execution of the
subscription-managercommand fails. If you use the
--proxyoption instead of the configuration change, the upgrade process fails because
Leappis unable to detect the proxy. To prevent this problem from occurring, manually edit the
rhsm.conffile as described in How to configure HTTP Proxy for Red Hat Subscription Management. (BZ#1689294)
If your RHEL 7 system uses a device driver that is provided by Red Hat but is not available in RHEL 8,
Leappinhibits the upgrade. However, if the RHEL 7 system uses a third-party device driver that
Leappdoes not have data for in the
Leappdoes 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
winsSamba modules are used in the
/etc/nsswitch.conffile. The upgrade transaction fails with the following error messages and
Leappinhibits the upgrade:
upgrade: STDERR: upgrade: Error in PREIN scriptlet in rpm package unbound-libs upgrade: Error: Transaction failed upgrade: 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
hostsdatabase during the update:
Open the system
/etc/nsswitch.confconfiguration file and search for entries that contain the
If you find such entries, create a backup of
winsfrom the entries that contain them.
- Perform an in-place upgrade.
After the upgrade, add the
winsstrings to their entries in
/etc/nsswitch.conf, based on your system configuration requirements.
- Open the system
Leapputility does not change customized authentication configuration during the upgrade process. If you used the deprecated
authconfigutility 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
During the in-place upgrade, the deprecated
pam_pkcs11pluggable authentication modules (PAM) are removed. As a result, if the PAM configuration on your RHEL 7 system contains the
pam_pkcs11modules and if these modules have the
requisitecontrol values, you might be locked out of the system if you perform the in-place upgrade. To work around this problem, reconfigure your RHEL 7 system to not use
pam_pkcs11before you start the upgrade process.
If the name of a third-party package (not signed by Red Hat) installed on your system is the same as the name of a package provided by Red Hat, the in-place upgrade fails. To work around this problem, select one of the following options prior to upgrading:
- Remove the third-party package
- Replace the third-party package with the package provided by Red Hat
For security reasons, support for single-DES (DES) and triple-DES (3DES) encryption types has been removed from RHEL 8. 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 IdM Default encryption types Additional supported encryption types
arcfour-hmac[a][a] RC4 encryption has been deprecated and disabled by default in RHEL 8 because it is considered less secure than the newer AES-128 and AES-256 encryption types. For more information about 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 enctypeencryption 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 about re-keying Kerberos principals to use stronger encryption types, see Retiring DES from MIT Kerberos Documentation.
- The in-place upgrade fails on systems with Software Redundant Array of Independent Disks (RAID). (BZ#1957192)
- Systems with a disabled GRUB boot loader specification, such as systems using Puppet, cannot create new initramfs for newer kernels. To work around this problem, manually remove packages and the old kernel from the boot loader entry as described in Chapter 6: Performing post-upgrade tasks. (BZ#1955099)
- The Relax-and-Recover (ReaR) utility is not available on the IBM Z architecture. As a result, IBM Z systems cannot be completely remediated by the OpenSCAP suite and might not be fully compliant with security baselines. (BZ#1958939)
During the in-place upgrade, the
Leapputility usually preserves the network interface controller (NIC) names between RHEL 7 and RHEL 8. However, on some systems, for example systems with network bonding, the NIC names might need to be updated between RHEL 7 and RHEL 8. On those systems, set the
LEAPP_NO_NETWORK_RENAMING=1environment variable, perform the in-place upgrade, and then verify that your network is working as expected. If needed, manually update the network configuration. (BZ#1919382)
The in-place upgrade might be inhibited because the
Leapputility incorrectly detects that there is not enough available disk space. If your system contains partitions formatted with the XFS filesystem without ftype attributes, you can work around this issue by changing the default size in the
LEAPP_OVL_SIZEenvironment variable to account for, at minimum, the specified missing disk space inside the container. It is recommended to increase the default size to greater than the specified missing disk space to prevent repeated error messages. For example, if the
Leapputility detects that an additional 400 MB is needed, increase the default size from 2048 MB to at least 2500 MB.Note
This workaround can require a large amount of free space in the
If this workaround does not resolve the issue, or if your system does not contain these partitions without ftype attributes, contact Red Hat support.
9.4. Known issues for IBM POWER 9 (little endian) and IBM Z (Structure A)
The IBM POWER 9 (little endian) and 64-bit IBM Z (Structure A) architectures have reached end of life. The final upgrade path for these architectures is from RHEL 7.6 to RHEL 8.4. Later releases to the in-place upgrade do not include these architectures. As a result, known issues that are resolved in later releases of the in-place upgrade are not resolved for these architectures.
The following known issues affect only IBM POWER 9 (little endian) and 64-bit IBM-Z (Structure A) architectures:
During an in-place upgrade, the
dockerpackage 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)
During the pre-upgrade process, users might need to answer true or false questions before they can proceed with the upgrade. If the pre-upgrade report was run prior to the release of the latest version of
Leapp, the report might have incorrectly reported that all true or false questions had been answered and that it was safe to proceed with the upgrade. If you ran the pre-upgrade report prior to November 9, 2021, complete the following steps to prevent serious issues with the upgrade:
# rm -f /var/log/leapp/answerfile /var/log/leapp/answerfile.userchoices
leapp preupgradecommand and answer any true or false questions again.
- Update all
On systems with the NSFD service running on NFS servers, a non-existent NFS partition might be incorrectly detected during the in-place upgrade, inhibiting the upgrade. To prevent this issue, stop the NFSD service before running the in-place upgrade:
# systemctl stop /proc/fs/nfsd
9.5. Obtaining support
To open a support case, select RHEL 7 as the product, and provide a
sosreport from your system.
To generate a
sosreporton your system, run:
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?.