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 is currently supported only from RHEL 7.6 to RHEL 8.1 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 can 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.
  • 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 can 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 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.

See also Section 6.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, you need to make the RHEL 8 repositories 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 RHEL 7 EUS repositories enabled if they are available for the given architecture and repository. 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.

    The following commands list repositories for the 64-bit Intel architecture; for other architectures, see Appendix A, RHEL 7 repositories.

    1. Enable the Base EUS repository:

      # subscription-manager repos --disable rhel-7-server-rpms --enable rhel-7-server-eus-rpms
    2. Enable the Extras repository where Leapp and its dependencies are available:

      # subscription-manager repos --enable rhel-7-server-extras-rpms
    3. If you have the Optional repository enabled, enable the Optional EUS repository:

      # subscription-manager repos --disable rhel-7-server-optional-rpms --enable rhel-7-server-eus-optional-rpms
    4. If you have the Supplementary repository enabled, enable the Supplementary EUS repository:

      # subscription-manager repos --disable rhel-7-server-supplementary-rpms --enable rhel-7-server-eus-supplementary-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
    Important

    The upgrade is designed for RHEL 7.6 as a starting point. If you have any packages from RHEL 7.7 or later installed on your system, the in-place upgrade is unsupported.

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

    # yum update
  7. Reboot the system:

    # reboot
  8. Install the Leapp utility:

    # yum install leapp
  9. 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.
  10. 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.
  11. 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.
  12. 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. Assessing upgradability in the pre-upgrade phase

During the pre-upgrade process, the Leapp utility collects data about the system, assesses upgradability, and produces a pre-upgrade report in the /var/log/leapp/leapp-report.txt file and in the web console. The report summarizes potential problems and proposes recommended resolutions. The report also helps you decide whether it is possible or advisable to proceed with the upgrade. Additionally, the web console enables you to apply automated remediations.

Important

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 pre-upgrade report, Leapp can still inhibit the upgrade process in later phases. For more information, see Chapter 6, Troubleshooting.

3.1. Performing the pre-upgrade assessment from the command line

This procedure describes how to identify potential upgrade problems during the pre-upgrade phase using the command-line interface.

Prerequisites

Procedure

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

    # leapp preupgrade
  2. Examine the report in the /var/log/leapp/leapp-report.txt file and manually resolve all the reported problems before proceeding with the in-place upgrade.

3.2. Performing the pre-upgrade assessment and remediations in the web console

This procedure describes how to identify potential problems in the pre-upgrade phase and how to apply automated remediations using the web console.

Prerequisites

Procedure

  1. Install the cockpit-leapp plug-in:

    # yum install cockpit-leapp
  2. Navigate to the web console in your browser and log in as root or as a user with sufficient privileges. See Managing systems using the RHEL 7 web console for more information about the web console.
  3. On your RHEL 7 system, perform the pre-upgrade phase either from the command-line interface or from the web console terminal:

    # leapp preupgrade
  4. In the web console, select In-place Upgrade Report from the left menu.

    Figure 3.1. In-place upgrade report in the web console

    In-place upgrade report in the web console

    The report table provides an overview of the problems found, their risk assessment, and remediations (if available).

    • Risk factor:

      • High - very likely to result in a deteriorated system state
      • Medium - can impact both the system and applications
      • Low - should not impact the system but can have an impact on applications
    • Inhibitor - will inhibit (hard stop) the upgrade process, otherwise the system could become unbootable, inaccessible, or dysfunctional
    • Remediation - an actionable solution to a reported problem:

      • Remediation command - can be executed directly through the web console
      • Remediation hint - instructions on how to resolve the problem manually
  5. Examine the content of the report. You can sort the table by clicking a header. To open a detail pane, click a selected row.

    Figure 3.2. Detail pane

    Detail pane

    The detail pane displays the following additional information:

    • Summary of the problem and links to Knowledgebase articles describing the problem in more detail
    • Remediations - you can run or schedule an automated remediation (if available), and see its results when applied
    • Affected system resources: packages, repositories, files (configuration, data), disks, volumes
  6. Optionally filter the results. Click the Filters button in the top left corner above the report and apply a filter based on your preferences. Filter categories are applied in conjunction with one another.

    Figure 3.3. Filters

    Filters
  7. Select issues for which you want to apply an automated remediation. You have two options:

    1. Choose individual items by clicking the Add to Remediation Plan button in the detail pane. Alternatively, you can execute individual remediations directly by clicking Run Remediation in the detail pane.
    2. Select all items for which a remediation is available by clicking the Add all remediations to plan button in the top right corner above the report.
  8. Open the remediation plan by clicking the Remediation plan link in the top right corner above the report. The remediation plan provides a list of all executed or scheduled remediations.

    Figure 3.4. Remediation plan

    Remediation plan
  9. Process all scheduled remediations by clicking Execute Remediation Plan. The following information is displayed for each remediation entry:

    • A unique ID of the remediation
    • Exit status of the command
    • Elapsed time of the executed remediation
    • Standard output
    • Standard error

Chapter 4. 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. 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 Chapter 3, Assessing upgradability in the pre-upgrade phase.

    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 6, Troubleshooting.

  2. 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 6, Troubleshooting.

  3. 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 6, Troubleshooting for more details.
      • Enable SELinux in enforcing mode:

        # setenforce 1
    3. Verify the state of the system as described in Chapter 5, Verifying the post-upgrade state of the RHEL 8 system.

Chapter 5. 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.1 (Ootpa)
  • Check the OS kernel version:

    # uname -r
    4.18.0-147.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.1
    Arch:         x86_64
    Status:       Subscribed
  • Verify that the release version is correctly set to 8.1:

    # subscription-manager release
    Release: 8.1

    Note that when the release version is set to 8.1, 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 6. Troubleshooting

This chapter lists troubleshooting resources and tips.

6.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/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 journalctl utility provides complete logs.

Reports

6.2. Troubleshooting tips

Pre-upgrade phase

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 5, 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.

6.3. Known issues

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

  • On non-UEFI systems, a traceback message similar to the following example might occur:

    [ 1034.874944] upgrade[436]: 2019-11-04 10:30:51.516 DEBUG    PID: 1387 leapp.workflow.Finalization.efi_finalization_fix: External command has finished: ['/sbin/efibootmgr']
    [ 1034.922455] upgrade[436]: Process Process-149:
    [ 1034.922601] upgrade[436]: Traceback (most recent call last):
    [ 1035.026117] upgrade[436]:   File "/usr/lib64/python3.6/multiprocessing/process.py", line 258, in _bootstrap
    [ 1035.026441] upgrade[436]:     self.run()
    ...
    [ 1035.952585] upgrade[436]:     exec_func(file, *argrest)
    [ 1036.056234] upgrade[436]: FileNotFoundError: [Errno 2] No such file or directory: '/sbin/efibootmgr'

    It is safe to ignore such messages, which do not affect the result of the upgrade process.

  • If an OpenStack configuration drive with the iso9660 type file system is present on the RHEL 7 system, the upgrade process might hang in the initramfs phase. To prevent the problem from occurring, remove such a drive from the system before the upgrade and re-create it on the upgraded system. (BZ#1712456)
  • It is currently impossible to perform an in-place upgrade when the winbind and wins Samba modules are used in the /etc/nsswitch.conf file. 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)

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

Appendix A. RHEL 7 repositories

Before the upgrade, it is necessary to have appropriate repositories enabled as described in step 3 of the procedure in Chapter 2, Preparing a RHEL 7 system for the upgrade.

It is especially necessary to have the appropriate Extended Update Support (EUS) repositories enabled if they are available for the given architecture and repository. Make sure your subscription includes the Red Hat Enterprise Linux for <architecture> - Extended Update Support product, where <architecture> is one of the following: x86_64, Power, little endian, IBM z Systems. You can purchase the EUS add-on for the 64-bit Intel architecture or contact a sales representative.

Note

EUS repositories are not available for the following architectures: 64-bit ARM, IBM POWER9 (little endian), IBM Z (Structure A).

The following repositories must be enabled before the upgrade by using the subscription-manager repos --enable repoid command:

ArchitectureRepositoryRepository ID

64-bit Intel

Base

rhel-7-server-eus-rpms

Extras

rhel-7-server-extras-rpms

64-bit ARM

Base

rhel-7-for-arm-64-rpms

Extras

rhel-7-for-arm-64-extras-rpms

IBM POWER8 (little endian)

Base

rhel-7-for-power-le-eus-rpms

Extras

rhel-7-for-power-le-extras-rpms

IBM POWER9 (little endian)

Base

rhel-7-for-power-9-rpms

Extras

rhel-7-for-power-9-extras-rpms

IBM Z

Base

rhel-7-for-system-z-eus-rpms

Extras

rhel-7-for-system-z-extras-rpms

IBM Z (Structure A)

Base

rhel-7-for-system-z-a-rpms

Extras

rhel-7-for-system-z-a-extras-rpms

The following repositories can be enabled before the upgrade by using the subscription-manager repos --enable repoid command:

ArchitectureRepositoryRepository ID

64-bit Intel

Optional

rhel-7-server-eus-optional-rpms

Supplementary

rhel-7-server-eus-supplementary-rpms

64-bit ARM

Optional

rhel-7-for-arm-64-optional-rpms

Supplementary

N/A

IBM POWER8 (little endian)

Optional

rhel-7-for-power-le-eus-optional-rpms

Supplementary

rhel-7-for-power-le-eus-supplementary-rpms

IBM POWER9 (little endian)

Optional

rhel-7-for-power-9-optional-rpms

Supplementary

rhel-7-for-p ower-9-supplementary-rpms

IBM Z

Optional

rhel-7-for-system-z-eus-optional-rpms

Supplementary

rhel-7-for-system-z-eus-supplementary-rpms

IBM Z (Structure A)

Optional

rhel-7-for-system-z-a-optional-rpms

Supplementary

N/A

The following repositories should be disabled by using the subscription-manager repos --disable repoid command, and their corresponding EUS repositories enabled (see the tables above):

ArchitectureRepositoryRepository ID

64-bit Intel

Base

rhel-7-server-rpms

Optional

rhel-7-server-optional-rpms

Supplementary

rhel-7-server-supplementary-rpms

IBM POWER8 (little endian)

Base

rhel-7-for-power-le-rpms

Optional

rhel-7-for-power-le-optional-rpms

Supplementary

rhel-7-for-power-le-supplementary-rpms

IBM Z

Base

rhel-7-for-system-z-rpms

Optional

rhel-7-for-system-z-optional-rpms

Supplementary

rhel-7-for-system-z-supplementary-rpms

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.