Red Hat Training

A Red Hat training course is available for RHEL 8

Upgrading to RHEL 8

Red Hat Enterprise Linux 8

Instructions for an in-place upgrade to Red Hat Enterprise Linux 8

Red Hat Customer Content Services

Abstract

This document provides instructions on how to perform an in-place upgrade from Red Hat Enterprise Linux 7 to Red Hat Enterprise Linux 8 using the Leapp utility. During the in-place upgrade, the existing RHEL 7 operating system is replaced by a RHEL 8 version.

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:

    1. Go to the Bugzilla website.
    2. As the Component, use Documentation.
    3. Fill in the Description field with your suggestion for improvement. Include a link to the relevant part(s) of documentation.
    4. Click Submit Bug.

Chapter 1. Requirements and known limitations

1.1. Requirements

An in-place upgrade to RHEL 8 is currently supported only on systems meeting the following requirements:

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 upgrade command, and set the size to more than 2048 MB (see a related solution for more information). To determine the ftype value, use the xfs_info command.
  • The whole system must be mounted under the root file system, with the exception of /home and /boot. For example, the /var or /usr directories 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.

Prerequisites

Procedure

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

  2. 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
  3. Make sure you have the Extended Update Support (EUS) repositories enabled. This is necessary for a successful update of the RHEL 7.6 system to the latest versions of packages in step 6 of this procedure, and a prerequisite for a supported in-place upgrade scenario.

    # subscription-manager repos --disable rhel-7-server-rpms --enable rhel-7-server-eus-rpms

    If you have the Optional channel enabled, enable also the Optional EUS repository by running:

    # subscription-manager repos --disable rhel-7-server-optional-rpms --enable rhel-7-server-eus-optional-rpms
  4. If you use the yum-plugin-versionlock plug-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.

  5. Set the Red Hat Subscription Manager to consume the RHEL 7.6 content:

    # subscription-manager release --set 7.6
    Note

    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.

  6. Update all packages to the latest RHEL 7.6 version:

    # yum update
  7. Reboot the system:

    # reboot
  8. Enable the Extras repository where some of the dependencies are available:

    # subscription-manager repos --enable rhel-7-server-extras-rpms
  9. Install the Leapp utility:

    # yum install leapp
  10. 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 /etc/leapp/files/ directory.
  11. 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.
  12. 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.
  13. 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.

Prerequisites

Procedure

  1. Optional: On your RHEL 7 system, perform the pre-upgrade phase separately:

    # leapp preupgrade

    During the pre-upgrade process, the Leapp utility collects data about the system, checks the upgradability, and produces a pre-upgrade report in the /var/log/leapp/leapp-report.txt file. This enables you to obtain early information about the planned upgrade and to assess whether it is possible or advisable to proceed with the upgrade.

  2. On your RHEL 7 system, start the upgrade process:

    # leapp upgrade

    At the beginning of the upgrade process, Leapp performs the pre-upgrade phase, described in the preceding step, and produces a pre-upgrade report in the /var/log/leapp/leapp-report.txt file.

    Note

    During the pre-upgrade phase, Leapp neither simulates the whole in-place upgrade process nor downloads all RPM packages, and even if no problems are reported in /var/log/leapp/leapp-report.txt, Leapp can still inhibit the upgrade process in later phases.

    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.txt file. For more information, see Chapter 5, Troubleshooting.

  3. Manually reboot the system:

    # reboot

    In this phase, the system boots into a 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.

  4. Perform the following post-upgrade tasks:

    1. Log in to the RHEL 8 system.
    2. 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
    3. Enable firewall:

      # systemctl start firewalld
      # systemctl enable firewalld

      See Using and configuring firewalls for more information.

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

Prerequisites

Procedure

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

    Note that .el8 is important.

  • 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 the release version is correctly set to 8.0:

    # subscription-manager release
    Release: 8.0

    Note that when the release version is set to 8.0, you will be receiving yum updates only for this specific version of RHEL. If you want to unset the release version to be able to consume updates from the latest minor version of RHEL 8, use the following command:

    # subscription-manager release --unset
  • 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

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/dnf-debugdata/ directory contains transaction debug data. This directory is present only if Leapp is executed with the --debug option.
  • The /var/log/leapp/leapp-upgrade.log file lists issues found during the initramfs phase.
  • The journalctl utility provides complete logs.

Reports

  • The /var/log/leapp/leapp-report.txt file lists issues found during the pre-upgrade phase.

5.2. Troubleshooting tips

Pre-upgrade phase

  • Verify that your system meets all conditions listed in Chapter 1, Requirements and known limitations. For example, use the df -h command to see whether the system has sufficient available space in the /boot partition.
  • 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 (eth).
  • Investigate the pre-upgrade report in the /var/log/leapp/leapp-report.txt file to determine the problem and a recommended solution.

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 into the dracut shell. Check the journal:

    # 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 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

  • 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-win package, due to missing mapping support for this channel. In addition, the corresponding RHEL 8 Supplementary repository fails to be enabled on the upgraded system. (BZ#1621775)
  • 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 will inhibit 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 will not detect such a driver and will proceed with the upgrade. Consequently, the system might fail to boot after the upgrade.
  • If you see the following error message:

    [ERROR] Actor: target_userspace_creator Message: There are no enabled target repositories for the upgrade process to proceed.
    Detail: {u'hint': u'Ensure your system is correctly registered with the subscription manager and that your current subscription is entitled to install the requested target version 8.0'}

    and you are sure that the appropriate subscription is correctly attached, check the presence of the repomap.csv and pes-events.json files in the /etc/leapp/files/ directory. If these files are missing, download them as described in step 10 of the procedure in Chapter 2, Preparing a RHEL 7 system for the upgrade.

  • If you see an error message similar to this:

    [ERROR] Actor: target_userspace_creator Message: A subscription-manager command failed to execute
    Detail: {u'hint': u'Please ensure you have a valid RHEL subscription and your network is up.'}

    while the RHEL server subscription is correctly attached and the network connection is functioning, check the RHEL 7 version from which you are trying to upgrade and make sure it is 7.6.

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

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:

# sosreport

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

Legal Notice

Copyright © 2019 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.