Red Hat Enterprise Linux in-place upgrades

Applies to: ✔️ Linux VMs

This article provides instructions about how to do an in-place upgrade from Red Hat Enterprise Linux (RHEL) 7 to Red Hat Enterprise Linux 8. The instructions use the leapp tool in Azure. During the in-place upgrade, the existing RHEL 7 operating system is replaced by the RHEL 8 version.

Note

Offerings of SQL Server on Red Hat Enterprise Linux don't support in-place upgrades on Azure.

What to expect during the upgrade

During the upgrade, the system restarts a few times. The final restart upgrades the VM to the RHEL 8 latest minor release.

The upgrade process can take anywhere from 20 minutes to 2 hours. The total time depends on several factors, such as the VM size and the number of packages installed on the system.

Preparations

Red Hat and Azure recommend using an in-place upgrade to transition a system to the next major version.

Before you start the upgrade, keep in mind the following considerations.

Important

Take a snapshot of the image before you start the upgrade.

  • Make sure you're using the latest RHEL 7 version. Currently, the latest version is RHEL 7.9. If you use a locked version and can't upgrade to RHEL 7.9, then follow these steps to switch to a non-EUS (extended update support) repository.

  • Run the following command to check on your upgrade and see whether it will finish successfully. The command should generate /var/log/leapp/leapp-report.txt file. This file explains the process, what's happening, and whether the upgrade is possible.

    Note

    Use the root account to run the commands in this article.

    leapp preupgrade --no-rhsm
    
  • Ensure the serial console is functional. You'll use this console for monitoring during the upgrade process.

  • Enable SSH root access in /etc/ssh/sshd_config:

    1. Open the file /etc/ssh/sshd_config.
    2. Search for #PermitRootLogin yes.
    3. Remove the number sign (#) to uncomment the string.

Upgrade steps

Follow these steps carefully. We recommend trying the upgrade on a test machine before you try it on production instances.

  1. Do a yum update to fetch the latest client packages.

    yum update -y
    
  2. Install the leapp-client-package.

    yum install leapp-rhui-azure
    
  3. In the Red Hat portal, obtain the leapp-data.tar.gz file that contains repomap.csv and pes-events.json. Extract the leapp-data.tar.gz file.

    1. Download the leapp-data.tar.gz file.
    2. Extract the contents and remove the file. Use the following command:
    tar -xzf leapp-data12.tar.gz -C /etc/leapp/files && rm leapp-data12.tar.gz
    
  4. Add an answers file for leapp.

    leapp answer --section remove_pam_pkcs11_module_check.confirm=True --add
    
  5. Start the upgrade.

    leapp upgrade --no-rhsm
    
  6. After the leapp upgrade command finishes successfully, manually restart the system to complete the process. The system is unavailable as it restarts a couple of times. Monitor the process by using the serial console.

  7. Verify the upgrade finished successfully.

    uname -a && cat /etc/redhat-release
    
  8. When the upgrade finishes, remove root SSH access:

    1. Open the file /etc/ssh/sshd_config.
    2. Search for #PermitRootLogin yes.
    3. Add a number sign (#) to comment the string.
  9. Restart the SSHD service to apply the changes.

    systemctl restart sshd
    

Common problems

The following errors commonly happen when either the leapp preupgrade process fails or the leapp upgrade process fails:

  • Error: No matches found for the following disabled plugin patterns.

    STDERR:
    No matches found for the following disabled plugin patterns: subscription-manager
    Warning: Packages marked by Leapp for upgrade not found in repositories metadata: gpg-pubkey
    

    Solution: Disable the subscription-manager plug-in. Disable it by editing the file /etc/yum/pluginconf.d/subscription-manager.conf and changing enabled to enabled=0.

    This error happens when the subscription-manager yum plug-in that's enabled isn't used for PAYG VMs.

  • Error: Possible problems with remote login using root.

    You might see this error when the leapp preupgrade fails:

    ============================================================
                         UPGRADE INHIBITED
    ============================================================
    
    Upgrade has been inhibited due to the following problems:
        1. Inhibitor: Possible problems with remote login using root account
    Consult the pre-upgrade report for details and possible remediation.
    
    ============================================================
                         UPGRADE INHIBITED
    ============================================================
    

    Solution: Enable root access in /etc/sshd_config.

    This error happens when root SSH access isn't enabled in /etc/sshd_config. For more information, see the Preparations section in this article.

Next steps