Upgrading to RHEL 8
Instructions for an in-place upgrade to Red Hat Enterprise Linux 8
Providing feedback on Red Hat documentation
We appreciate your input on our documentation. Please let us know how we could make it better. To do so:
- For simple comments on specific passages, make sure you are viewing the documentation in the Multi-page HTML format. Highlight the part of text that you want to comment on. Then, click the Add Feedback pop-up that appears below the highlighted text, and follow the displayed instructions.
For submitting more complex feedback, create a Bugzilla ticket:
- Go to the Bugzilla website.
- As the Component, use Documentation.
- Fill in the Description field with your suggestion for improvement. Include a link to the relevant part(s) of documentation.
- Click Submit Bug.
Chapter 1. Requirements and known limitations
An in-place upgrade to RHEL 8 is currently supported only on systems meeting the following requirements:
- RHEL 7.6 installed
- The Server variant
- The Intel 64 architecture
At least 100MB of free space available on the boot partition (mounted at
- FIPS mode disabled; see the solution How to disable FIPS mode in RHEL 6 or RHEL 7
- Minimum hardware requirements for RHEL 8; see Red Hat Enterprise Linux technology capabilities and limits
- The system registered to the Red Hat Content Delivery Network or Red Hat Satellite 6.5 or later using the Red Hat Subscription Manager
1.2. Known limitations
Notable known limitations currently include:
- A rollback to the last known good state has not been implemented in the Leapp utility. A complete system backup prior to the upgrade is recommended, for example, by using the Relax-and-Recover (ReaR) utility. For more information, see the ReaR documentation and What is Relax and Recover (ReaR) and how can I use it for disaster recovery?.
Packages that are not a part of the Minimal (
@minimal) or Base (
@base) package groups might cause the upgrade to fail.
- No disk, LVM, or file-system encryption can currently be used on a system targeted for an in-place upgrade.
- No Multipath or any kind of network storage mount can be used as a system partition (for example, iSCSI, FCoE, or NFS).
- During the upgrade process, the Leapp utility sets SELinux mode to permissive and disables firewall.
- No support for other Red Hat products running on top of the OS, Red Hat Software Collections, Red Hat Developer Tools, or add-ons, such as High Availability or Network Function Virtualization, is currently provided.
On systems where the root file system is formatted as XFS with
ftype=0(default in RHEL 7.2 and earlier versions), the RPM upgrade transaction calculation might fail if numerous packages are installed on the system. If the cause of such a failure is insufficient space, increase the available space by using the
LEAPP_OVL_SIZE=<SIZE_IN_MB>environment variable with the
leapp upgradecommand, and set the size to more than 2048 MB (see a related solution for more information). To determine the
ftypevalue, use the
The whole system must be mounted under the root file system, with the exception of
/boot. For example, the
/usrdirectories cannot be mounted on a separate partition.
- The in-place upgrade is currently unsupported for on-demand instances on Public Clouds (Amazon EC2, Azure, Huawei Cloud, Alibaba Cloud, Google Cloud) that use Red Hat Update Infrastructure but not Red Hat Subscription Manager for a RHEL subscription.
- UEFI is currently unsupported.
See also Section 5.3, “Known issues”.
Chapter 2. Preparing a RHEL 7 system for the upgrade
This procedure describes the steps that are necessary before performing an in-place upgrade to RHEL 8 using the Leapp utility.
- The system meets conditions listed in Chapter 1, Requirements and known limitations.
Make sure your system has been successfully registered to the Red Hat Content Delivery Network (CDN) or Red Hat Satellite 6.5 or later using the Red Hat Subscription Manager.Note
If your system is registered to a Satellite Server, the RHEL 8 repositories need to be made available by importing a Subscription Manifest file, created in the Red Hat Customer Portal, into the Satellite Server. For instructions, see the Managing Subscriptions section in the Content Management Guide for the particular version of Red Hat Satellite, for example, for version 6.5.
Verify that you have the Red Hat Enterprise Linux Server subscription attached.
# subscription-manager list --installed +-------------------------------------------+ Installed Product Status +-------------------------------------------+ Product Name: Red Hat Enterprise Linux Server Product ID: 69 Version: 7.6 Arch: x86_64 Status: Subscribed
If you use the
yum-plugin-versionlockplug-in to lock packages to a specific version, clear the lock by running:
# yum versionlock clear
See How to restrict yum to install or upgrade a package to a fixed specific package version? for more information.
Set the Red Hat Subscription Manager to consume the RHEL 7.6 content:
# subscription-manager release --set 7.6Note
The upgrade is designed for RHEL 7.6 as a starting point. If you have any packages from a later version of RHEL, please downgrade them to their RHEL 7.6 versions.
Update all packages to the latest RHEL 7.6 version:
# yum update
Reboot the system:
Enable the Extras repository where some of the dependencies are available:
# subscription-manager repos --enable rhel-7-server-extras-rpms
Install the Leapp utility:
# yum install leapp
Download additional required data files (RPM package changes and RPM repository mapping) attached to the Knowledgebase article Data required by the Leapp utility for an in-place upgrade from RHEL 7 to RHEL 8 and place them in the
- Make sure you have any configuration management (such as Salt, Chef, Puppet, Ansible) disabled or adequately reconfigured to not attempt to restore the original RHEL 7 system.
Make sure your system does not use more than one Network Interface Card (NIC) with a name based on the prefix used by the kernel (
eth). For instructions on how to migrate to another naming scheme before an in-place upgrade to RHEL 8, see How to perform an in-place upgrade to RHEL 8 when using kernel NIC names on RHEL 7.
- Make sure you have a full system backup or a virtual machine snapshot. You should be able to get your system to the pre-upgrade state if you follow standard disaster recovery procedures within your environment.
Chapter 3. Performing the upgrade from RHEL 7 to RHEL 8
This procedure describes how to upgrade to RHEL 8 using the Leapp utility.
- The steps listed in Chapter 2, Preparing a RHEL 7 system for the upgrade have been completed, including a full system backup.
On your RHEL 7 system, start the upgrade process:
# leapp upgrade
In this phase, the Leapp utility collects data about your system, checks the upgradability, and produces a pre-upgrade report in the
If the system is upgradable, Leapp downloads necessary data and prepares an RPM transaction for the upgrade.
If your system does not meet the parameters for a reliable upgrade, Leapp terminates the upgrade process and provides a record describing the issue and a recommended solution in the
/var/log/leapp/leapp-report.txtfile. For more information, see Chapter 5, Troubleshooting.
Manually reboot the system:
In this phase, the system boots into an RHEL 8-based initial RAM disk image, initramfs. Leapp upgrades all packages and automatically reboots to the RHEL 8 system.
If a failure occurs, investigate logs as described in Chapter 5, Troubleshooting.
Perform the following post-upgrade tasks:
- Log in to the RHEL 8 system.
Change SELinux mode to enforcing:
- Ensure that there are no SELinux denials before you switch from permissive mode, for example, by using the ausearch utility. See Chapter 5, Troubleshooting for more details.
Enable SELinux in enforcing mode:
# setenforce 1
# systemctl start firewalld # systemctl enable firewalld
See Using and configuring firewalls for more information.
Unset the RHEL 7.6 version to be able to consume
yumupdates for RHEL 8 correctly:
# subscription-manager release --unset
- Verify the state of the system as described in Chapter 4, Verifying the post-upgrade state of the RHEL 8 system.
Chapter 4. Verifying the post-upgrade state of the RHEL 8 system
This procedure lists steps recommended to perform after an in-place upgrade to RHEL 8.
- The system has been upgraded following the steps described in Chapter 3, Performing the upgrade from RHEL 7 to RHEL 8 and you were able to log in to RHEL 8.
After the upgrade completes, determine whether the system is in the required state, at least:
Verify that the current OS version is Red Hat Enterprise Linux 8:
# cat /etc/redhat-release Red Hat Enterprise Linux release 8.0 (Ootpa)
Check the OS kernel version:
# uname -r 4.18.0-80.el8.x86_64
Verify that the correct product is installed:
# subscription-manager list --installed +-----------------------------------------+ Installed Product Status +-----------------------------------------+ Product Name: Red Hat Enterprise Linux for x86_64 Product ID: 479 Version: 8.0 Arch: x86_64 Status: Subscribed
- Verify that network services are operational, for example, try to connect to a server using SSH.
Chapter 5. Troubleshooting
This chapter lists troubleshooting resources and tips.
5.1. 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, Leapp prints info, warning, error, and critical messages.
- In debug mode, Leapp prints debug, info, warning, error, and critical messages.
/var/log/leapp/dnf-debugdata/directory contains transaction debug data. This directory is present only if Leapp is executed with the
/var/log/leapp/leapp-upgrade.logfile lists issues found during the initramfs phase.
- The journalctl utility provides complete logs.
/var/log/leapp/leapp-report.txtfile lists issues found during the pre-upgrade phase.
5.2. Troubleshooting tips
Verify that your system meets all conditions listed in Chapter 1, Requirements and known limitations. For example, use the
df -hcommand to see whether the system has sufficient available space in the
Make sure you have followed all steps described in Chapter 2, 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 (
Investigate the pre-upgrade report in the
/var/log/leapp/leapp-report.txtfile to determine the problem and a recommended solution.
If a problem occurs during downloading RPM packages, examine transaction debug data located in the
During this phase, potential failures redirect you into the dracut shell. Check the journal:
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 Chapter 4, 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 recent # 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.
5.3. Known issues
Under certain circumstances, traceback messages similar to the following example might occur:
2019-02-11T08:00:38Z CRITICAL Traceback (most recent call last): File "/usr/lib/python2.7/site-packages/dnf/yum/rpmtrans.py", line 272, in callback File "/usr/lib/python2.7/site-packages/dnf/yum/rpmtrans.py", line 356, in _uninst_progress File "/usr/lib/python2.7/site-packages/dnf/yum/rpmtrans.py", line 244, in _extract_cbkey RuntimeError: TransactionItem not found for key: lz4
It is safe to ignore such messages, which neither interrupt nor affect the result of the upgrade process.
- Network teaming currently does not work when the in-place upgrade is performed while Network Manager is disabled or not installed. (BZ#1717330)
The Leapp utility currently fails to upgrade packages from the Supplementary channel, such as the
virtio-winpackage, due to missing mapping support for this channel. (BZ#1621775)
RHEL 8 packages that use RPM rich dependencies cause failure during the upgrade transaction check. So far,
redhat-rpm-configwith its dependencies and
tpm2-abrmdhave been identified to cause such a problem. These packages are removed during the upgrade process by Leapp.
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 Leapp is 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 is installed on an FCoE Logical Unit Number (LUN) and connected to a network card that uses the
bnx2fcdriver, the LUN is not detected in RHEL 8 after the upgrade. Consequently, the upgraded system fails to boot. (BZ#1718147)
5.4. Obtaining support
To 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:
Note that you can leave the case ID empty.
For details on generating a sosreport, see the solution What is a sosreport and how to create one in Red Hat Enterprise Linux 4.6 and later?.
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?.