Performing the upgrade

Guide
  • Red Hat Enterprise Linux 8
  • Updated 15 October 2020
  • Published 04 November 2020

Performing the upgrade

Red Hat Enterprise Linux 8
  • Updated 15 October 2020
  • Published 04 November 2020

To upgrade to RHEL 8, you need to prepare your RHEL 7 system, upgrade using the command line in the web console, and verify the post-upgrade state.

Planning an upgrade

An in-place upgrade is the recommended and supported way to migrate your system to the next major version of RHEL.

You should consider the following before upgrading to RHEL 8:

  • Operating system - The operating system is upgraded by the Leapp utility under the following conditions:

  • Applications - You can migrate applications installed on your system using Leapp. However, in certain cases, you have to create custom actors, which specify actions to be performed by Leapp during the upgrade, for example, reconfiguring an application or installing a specific hardware driver. For more information, see Handling the migration of your custom and third-party applications. Note that custom actors are unsupported by Red Hat.

  • Security - You should evaluate this aspect before the upgrade and take additional steps when the upgrade process completes. Consider especially the following:

    • Before the upgrade, define the security standard your system needs to comply with and understand the security changes in RHEL 8.

    • During the upgrade process, the Leapp utility sets SELinux mode to permissive.

    • In-place upgrades of systems in FIPS mode are not supported.

    • After the upgrade is finished, re-evaluate and re-apply your security policies. For information about applying security policies that have been disabled during the upgrade or newly introduced in RHEL 8, see Applying security policies.

  • Storage and file systems - You should always back up your system prior to upgrading. For example, you can use the Relax-and-Recover (ReaR) utility, LVM snapshots, RAID splitting, or a virtual machine snapshot.

  • Downtime - The upgrade process can take from several minutes to several hours.

  • Satellite - If you manage your hosts through Satellite, you can upgrade multiple hosts simultaneously from RHEL 7 to RHEL 8 using the Satellite web UI. For more information, see Upgrading Hosts from RHEL 7 to RHEL 8.

  • Public Clouds - The in-place upgrade is supported for on-demand instances on Amazon Web Services (AWS) and Microsoft Azure, using Red Hat Update Infrastructure (RHUI).

  • Known limitations - Notable known limitations of Leapp currently include:

    • Encryption of the whole disk or a partition, or file-system encryption currently cannot be used on a system targeted for an in-place upgrade.

    • No network-based multipath and no kind of network storage mount can be used as a system partition (for example, iSCSI, or NFS).

    • The in-place upgrade is currently unsupported for on-demand instances on the remaining Public Clouds (Huawei Cloud, Alibaba Cloud, Google Cloud) that use Red Hat Update Infrastructure but not Red Hat Subscription Manager for a RHEL subscription.

See also Known Issues.

You can use Red Hat Insights to determine which of the systems you have registered to Insights is on a supported upgrade path to RHEL 8. To do so, navigate to the respective Advisor recommendation in Insights, enable the recommendation under the Actions drop-down menu, and inspect the list under the Affected systems heading. Note that the Advisor recommendation considers only the RHEL 7 minor version and does not perform a pre-upgrade assessment of the system.

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.

If you do not plan to use Red Hat Subscription Manager during the upgrade process, follow instructions in Upgrading to RHEL 8 without Red Hat Subscription Manager.

Prerequisites
Procedure
  1. Ensure 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.

    If your system is registered to Satellite Server, ensure that Satellite meets the following conditions:

    1. Satellite has a subscription manifest with RHEL 8 repositories imported. For more information, see the Managing Subscriptions chapter in the Content Management Guide for the particular version of Red Hat Satellite, for example, for version 6.7.

    2. The following repositories are enabled and synchronized with the latest updates, and published on Satellite:

      • Red Hat Enterprise Linux 7 Server RPMs x86_64 7 or Red Hat Enterprise Linux 7 Server RPMs x86_64 7.9

      • Red Hat Enterprise Linux 7 Server - Extras (RPMs)

      • Red Hat Enterprise Linux 8 for x86_64 - AppStream RPMs x86_64 8.2

      • Red Hat Enterprise Linux 8 for x86_64 - BaseOS RPMs x86_64 8.2

        For more information, see the Importing Red Hat Content chapter in the Content Management Guide for the particular version of Red Hat Satellite, for example, for version 6.7.

  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.9
    Arch:           x86_64
    Status:         Subscribed

    You should see Server in the product name and Subscribed as the status.

  3. Ensure you have appropriate repositories enabled. The following commands list repositories for the 64-bit Intel architecture; for other architectures, see RHEL 7 repositories.

    1. Enable the Base repository:

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

      # subscription-manager repos --enable rhel-7-server-extras-rpms

      You can also have the Optional or Supplementary repositories enabled; see their list in RHEL 7 repositories. In such a case, Leapp enables the RHEL 8 CodeReady Linux Builder or the RHEL 8 Supplementary repositories, respectively.

  4. Set the Red Hat Subscription Manager to consume the latest RHEL 7 content:

    # subscription-manager release --unset
  5. Optional: If you want to use custom repositories, configure them per instructions in Configuring custom repositories.

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

  7. Ensure you have the system locale set to en_US.UTF-8:

    $ cat /etc/locale.conf

    If the locale is different, follow instructions in How to change system locale on RHEL7?.

  8. If you are upgrading using Red Hat Update Infrastructure (RHUI) on a public cloud, complete the following tasks to ensure your system is ready for upgrade.

    1. For AWS, enable the Red Hat Update Infrastructure 3 Client Configuration Server 7 repository and install required RHUI packages.

      1. For non-ARM architectures:

        # yum-config-manager --enable rhui-client-config-server-7
        # yum -y install rh-amazon-rhui-client leapp-rhui-aws
      2. For the ARM architecture:

        # yum-config-manager --enable rhui-client-config-server-7-arm
        # yum -y install rh-amazon-rhui-client-arm leapp-rhui-aws
    2. For Microsoft Azure, enable the Microsoft Azure RPMs for Red Hat Enterprise Linux 7 repository and install required RHUI packages.

      # yum-config-manager --enable rhui-microsoft-azure-rhel7
      # yum -y install rhui-azure-rhel7 leapp-rhui-azure

      If you locked the Azure virtual machine (VM) to a minor release, remove the version lock. For more information, see Switch a RHEL 7.x VM back to non-EUS.

  9. Update all packages to the latest RHEL 7 version:

    # yum update
  10. Reboot the system:

    # reboot
  11. Install the Leapp utility:

    # yum install leapp leapp-repository

    Note that currently you need version 0.11.1 or later of the leapp package and version 0.12.0 or later of the leapp-repository package.

  12. 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. This is necessary for a successful upgrade. Note that currently you need data files from the leapp-data12.tar.gz archive or later.

    If you are upgrading on a public cloud using RHUI and do not have a Red Hat subscription or Red Hat Customer Portal account, create a no-cost RHEL developer subscription so that you can access the Knowledgebase article and download required data packages. For more information, see How do I get a no-cost Red Hat Enterprise Linux Developer Subscription or renew it?

  13. Ensure 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.

  14. Ensure 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.

  15. Ensure 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. For example, you can use 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?. Alternatively, you can use LVM snapshots, or RAID splitting. In case of upgrading a virtual machine, you can create a snapshot of the whole VM.

Reviewing the pre-upgrade report

To assess upgradability of your system, start the pre-upgrade process by the leapp preupgrade command. During this phase, the Leapp utility collects data about the system, assesses upgradability, and generates a pre-upgrade report.

The pre-upgrade report is available both in the /var/log/leapp/leapp-report.txt file and in the web console. The report summarizes potential problems and proposes recommended solutions. The report also helps you decide whether it is possible or advisable to proceed with the upgrade.

In certain configurations, Leapp generates true/false questions to determine how to proceed. All questions are stored in /var/log/leapp/answerfile and in the pre-upgrade report in the Missing required answers in the answer file message. Leapp inhibits the upgrade if you do not provide answers to all the questions.

You have two options when assessing upgradability in the pre-upgrade phase:

  1. Review the pre-upgrade report in the generated leapp-report.txt file and manually resolve reported problems using the command-line interface.

  2. Use the web console to review the report, apply automated remediations where available, and fix remaining problems using the suggested remediation hints.

During the pre-upgrade phase, Leapp neither simulates the whole in-place upgrade process nor downloads all RPM packages.

Reviewing a pre-upgrade report is useful also if you decide or need to redeploy a RHEL 8 system without the in-place upgrade process.

Assessing upgradability from the command line

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

    If you are going to use custom repositories from the /etc/yum.repos.d/ directory for the upgrade, enable the selected repositories as follows:

    # leapp preupgrade --enablerepo repository_id1 --enablerepo repository_id2 ...

    If you are going to upgrade without RHSM or using RHUI, add the --no-rhsm option.

  2. Provide answers to each question required by Leapp by either of the following methods:

    1. Execute the leapp answer command, specifying the question you are responding to and your confirmed answer.

      # leapp answer --section question_section.confirm=answer

      For example, to confirm a True response to the question Disable pam_pkcs11 module in PAM configuration?, execute the following command:

      # leapp answer --section remove_pam_krb5_module_check.confirm=True
    2. Manually edit the /var/log/leapp/answerfile file, uncomment the confirm line of the file by deleting the # symbol, and confirm your answer as True or False; see Leapp answerfile in the Troubleshooting tips section.

troubleshooting-tips

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

Assessing upgradability and applying automated remediations through the web console

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 configured in the /etc/sudoers file. 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

    If you are going to use custom repositories from the /etc/yum.repos.d/ directory for the upgrade, enable the selected repositories as follows:

    # leapp preupgrade --enablerepo repository_id1 --enablerepo repository_id2 ...

    If you are going to upgrade without RHSM or using RHUI, add the --no-rhsm option.

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

    In-place upgrade report in the web console
    Figure 1. 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.

    Detail pane
    Figure 2. 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.

    Filters
    Figure 3. 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. Review and answer questions required by Leapp in the web console. Each unanswered question appears as a Missing required answers in the answer file title in the Upgrade Report. Select a title to answer the question:

    1. To confirm the default True answer, select Add to Remediation Plan to execute the remediation later or Run Remediation to execute the remediation immediately.

    2. To select the non-default answer instead, perform either of the following:

      1. Execute the leapp answer command, specifying the question you are responding to and your confirmed answer.

        # leapp answer --section question_section.confirm=answer

        For example, to confirm a False response to the question Disable pam_pkcs11 module in PAM configuration?, execute the following command:

        # leapp answer --section remove_pam_krb5_module_check.confirm=False
      2. Manually edit the /var/log/leapp/answerfile file, uncomment the confirm line of the file by deleting the # symbol, and confirm your answer as True or False; see Leapp answerfile example in the Troubleshooting tips section.

        Unanswered Leapp question
        Figure 4. Missing unanswered Leapp question
  9. 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.

    Remediation plan
    Figure 5. Remediation plan
  10. 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

  11. After executing selected remediations, generate the pre-upgrade report again by using the leapp preupgrade command, examine the new report, and take additional remediation steps if needed.

Performing the upgrade from RHEL 7 to RHEL 8

Upgrade to RHEL 8 using the Leapp utility.

Prerequisites
Procedure
  1. On your RHEL 7 system, start the upgrade process:

    # leapp upgrade

    If you are going to use custom repositories from the /etc/yum.repos.d/ directory for the upgrade, enable the selected repositories as follows:

    # leapp upgrade --enablerepo repository_id1 --enablerepo repository_id2 ...

    If you are going to upgrade without RHSM or using RHUI, add the --no-rhsm option.

    At the beginning of the upgrade process, Leapp performs the pre-upgrade phase described in Reviewing the pre-upgrade report

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

    Alternatively, you can run the leapp upgrade command with the --reboot option and skip this manual step.

    If a failure occurs, investigate logs as described in Troubleshooting.

  3. Log in to the RHEL 8 system and verify its state as described in Verifying the post-upgrade state of the RHEL 8 system.

  4. Re-evaluate and re-apply your security policies. Especially, change the SELinux mode to enforcing. For details, see Applying security policies.

  5. If you upgraded using RHUI on AWS or Microsoft Azure and your software certification is not available on a later minor release version, lock your system to a minor release version supported by your certification.

    # echo '8.x' > /etc/yum/vars/releasever

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

    # uname -r
    4.18.0-193.el8.x86_64

    Note that .el8 is important.

  • If you are using the Red Hat Subscription Manager:

    • 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.2
      Arch:         x86_64
      Status:       Subscribed
    • Verify that the release version is set to 8.2 immediately after the upgrade:

      # subscription-manager release
      Release: 8.2
    • Ensure your system remains supported after the in-place upgrade. With the general availability of RHEL 8.3, update your system either to RHEL 8.3 or to RHEL 8.2 Extended Update Support (EUS).

      1. Update the system to RHEL 8.3:

        1. Unset Red Hat Subscription Manager to consume the latest RHEL 8.3 content:

          # subscription-manager release --unset
        2. Update your system to the latest RHEL 8.3 version:

          # yum update
      2. Update the system to RHEL 8.2 EUS:

        1. Enable RHEL 8 EUS repositories:

          # subscription-manager repos --enable repository_id1 --enable repository_id2 …

          Replace repository_id* with IDs of EUS repositories available with your subscription. Enable at least the BaseOS and AppStream repositories. For example, on the Intel 64 architecture:

          # subscription-manager repos --enable  rhel-8-for-x86_64-baseos-eus-rpms --enable rhel-8-for-x86_64-appstream-eus-rpms
        2. Update your system to the latest RHEL 8.2.EUS version

          # yum update
  • Verify that network services are operational, for example, try to connect to a server using SSH.

  • Check the post-upgrade status of your applications. In some cases, you may need to perform migration and configuration changes manually. For example, to migrate your databases, follow instructions in RHEL 8 Database servers documentation.

Appendix A: RHEL 7 repositories

Before the upgrade, ensure you have appropriate repositories enabled as described in step 3 of the procedure in Preparing a RHEL 7 system for the upgrade.

If you plan to use Red Hat Subscription Manager during the upgrade, you must enable the following repositories before the upgrade by using the subscription-manager repos --enable repository_id command:

Architecture Repository Repository ID

64-bit Intel

Base

rhel-7-server-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-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-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

You can enable the following repositories before the upgrade by using the subscription-manager repos --enable repository_id command:

Architecture Repository Repository ID

64-bit Intel

Optional

rhel-7-server-optional-rpms

Supplementary

rhel-7-server-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-optional-rpms

Supplementary

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

IBM POWER9 (little endian)

Optional

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

Supplementary

rhel-7-for-power-9-supplementary-rpms

IBM Z

Optional

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

Supplementary

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

IBM Z (Structure A)

Optional

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

Supplementary

N/A

If you have enabled a RHEL 7 Optional or a RHEL 7 Supplementary repository before an in-place upgrade, Leapp enables the RHEL 8 CodeReady Linux Builder or RHEL 8 Supplementary repositories, respectively.

If you decide to use custom repositories, enable them per instructions in Configuring custom repositories.