Chapter 1. How to Upgrade

As of Red Hat Enterprise Linux 7.0 GA, there is one supported upgrade path: from the latest version of Red Hat Enterprise Linux 6 to the latest version of Red Hat Enterprise Linux 7.

1.1. How to upgrade from Red Hat Enterprise Linux 6

Follow the procedures in this chapter to upgrade to Red Hat Enterprise Linux 7 from Red Hat Enterprise Linux 6. The upgrade process consists of the following steps:
  1. Check that Red Hat supports the upgrade of your system. See Section 1.1.1, “Check your support status” for details.
  2. Prepare your system for upgrade. See Section 1.1.2, “Prepare your system for upgrade” for details.
  3. Check your system for problems that might affect your upgrade. See Section 1.1.3, “Check system upgrade suitability” for details.
  4. Upgrade by running the Red Hat Upgrade Tool. See Section 1.1.4, “Upgrade your system” for details.

1.1.1. Check your support status

Upgrading from Red Hat Enterprise Linux 6 to Red Hat Enterprise Linux 7 is supported only if your system meets the following criteria.
  • Your system is on the latest version of the Server variant of Red Hat Enterprise Linux 6 for Intel 64 and AMD64 architecture, with all packages up to date. To check, enter the following commands:
    # cat /etc/redhat-release
    Red Hat Enterprise Linux Server release 6.9 (Santiago)
    # arch
    x86_64
    # yum upgrade -y
  • Your system is registered to receive updates from Subscription Management and not RHN Classic.
  • Your system includes only the following package groups: Minimal, Base, Web Server, DHCP Server, NFS File Server (@nfs-server), and Print Server. Remove other package groups before upgrading and reinstall them when your upgrade is complete.
Check the following Knowledgebase Solution for details: https://access.redhat.com/solutions/799813.

1.1.2. Prepare your system for upgrade

Red Hat Enterprise Linux 7 is the first major release to allow in-place upgrades from the previous major version. Upgrades of this magnitude are complex and prone to error. To ensure your upgrade goes as smoothly as possible, some preparations are necessary.
Back up all data
Firstly, back up the entire system to avoid potential data loss, and test that your backup works.
Test first
Before you upgrade a production system, you should clone the system and test the upgrade procedure on the clone. This will allow you to prepare for upgrade without risking the production system.
Convert to Red Hat Subscription Management
Red Hat Enterprise Linux 7 must be registered with the Subscription Management tool (subscription-manager) rather than RHN Classic tools like rhn_register. See https://access.redhat.com/articles/433903 for details on getting started with Subscription Management.
Before it begins upgrading packages, the yum upgrade command outputs a statement about how this system receives updates. Ensure that subscription-manager and not RHN is mentioned here.
# yum upgrade
Loaded plugins: product-id, security, subscription-manager
...
If your Red Hat Enterprise Linux 6 system is currently registered to RHN Classic, you must first unregister from RHN Classic by following these instructions: https://access.redhat.com/solutions/11272.
Ensure only supported package groups are installed
This upgrade process supports only the following package groups: Minimal, Base, Web Server, DHCP Server, NFS File Server (@nfs-server), and Print Server. Check which package groups are installed with the yum grouplist command. Remove other package groups before upgrading and reinstall them when your upgrade is complete.
Update all packages
Once your system is registered with Subscription Management, ensure that all packages on your system are up to date by running the following commands.
# yum update -y
# reboot

1.1.3. Check system upgrade suitability

The Preupgrade Assistant checks your Red Hat Enterprise Linux 6 system for anything that might adversely affect the success of your upgrade.

1.1.3.1. Installing the Preupgrade Assistant

  1. Enable the Extras repository

    As root, run the following command to subscribe your system to the repository containing the Preupgrade Assistant.
    If your system receives updates from Red Hat Subscription Management:
    # subscription-manager repos --enable rhel-6-server-extras-rpms
  2. Install the tool

    As root, run the following command to install all the Preupgrade Assistant packages.
    # yum -y install preupgrade-assistant preupgrade-assistant-el6toel7

1.1.3.2. Running the Preupgrade Assistant

To run the Preupgrade Assistant, execute the following command as root.
# preupg -v
This takes a few minutes to complete.
Alternatively, if you have already configured a Preupgrade Assistant Web UI that this system can access, execute the following, replacing hostname and port with the appropriate values for your Preupgrade Assistant Web UI:
# preupg -v -u http://hostname:port/submit
See Section 1.1.3.2.1, “Configuring the Preupgrade Assistant Web UI” for instructions on setting up the web UI.
1.1.3.2.1. Configuring the Preupgrade Assistant Web UI
Preupgrade Assistant Web UI lets you upload and view preupgrade results via a browser-based interface. This is useful when the system you intend to upgrade is headless or does not have a graphical user environment.

Warning

Preupgrade Assistant Web UI requires a running instance of Apache Web Server (httpd) and a number of changes to the /etc/httpd/conf.d directory. If you are concerned about exposing data about your system to the network, or you want to avoid adding packages to the system you intend to upgrade, do not follow this procedure. Instead, copy the /root/preupgrade/result.html file to a machine with a graphical user interface and view it in a web browser.
  1. Install required packages

    # yum -y install httpd preupgrade-assistant-ui
  2. Change upload configuration

    Change from using the default private preupgrade configuration to the public configuration.
    # cd /etc/httpd/conf.d
    # cp 99-preup-httpd.conf.public 99-preup-httpd.conf
    This makes the Preupgrade Assistant Web UI available to all network interfaces on the local system, through TCP port 8099 by default.
    You can also edit the NameVirtualHost variable in the new /etc/httpd/conf.d/99-preup-httpd.conf to set a host name, if you want to access Preupgrade Assistant Web UI through a host name like preupg-ui.example.com:8099 instead of an IP address like 192.168.99.1:8099.
  3. Change firewall and SELinux configuration

    Temporarily put SELinux in permissive mode, and allow traffic through TCP port 8099.
    # setenforce 0
    # iptables -I INPUT -m state --state NEW -p tcp --dport 8099 -j ACCEPT
  4. Restart the web server

    # service httpd restart
  5. Configure or disable authentication

    In a web browser, navigate to http://192.168.99.1:8099/ (or the host name, if you specified one in Step 2). You are prompted to either enter details to create a new administrative user, or disable authentication.
You can now upload preupgrade test results from the system you intend to upgrade by running the preupg command with the -u http://hostname:port/submit option on that system.

1.1.3.3. Viewing results and correcting errors

When you run preupg, a summary of results is printed to standard output. Detailed results are saved to the /root/preupgrade directory as result.html by default. You can also upload results to the Preupgrade Assistant Web UI to compare multiple preupg runs as you correct potential migration issues.
Regardless of how you view the assessment results, you need to check each item for corrections that need to be made before you upgrade. Each item is printed with an exit code that indicates that item's suitability for in-place upgrade, as described in Table 1.1, “Exit Codes”.

Table 1.1. Exit Codes

Exit Code
Definition
PASS
Everything looks fine, and this item is ready to upgrade.
FAIL
Extreme upgrade risk. upgrade is not possible.
NEEDS_ACTION
High upgrade risk. Some administrator action is required before you upgrade.
NEEDS_INSPECTION
Moderate and lower risk. Upgrading should succeed, but may result in a system that is not fully functional.
FIXED
A change required for upgrade was made automatically.
INFORMATIONAL
Useful but non-critical information about this item is available in the report.
NOT_APPLICABLE
Preupgrade checked for an item that was not installed on your system.
ERROR
Something has probably gone wrong with the preupgrade tools. Report this type of problem to Red Hat Support.
Take note of any post-upgrade tasks identified by Preupgrade Assistant; you will need to perform these after you run the Red Hat Upgrade Tool.
You should also check the Release Notes, Technical Notes, and Migration Planning Guide for items that the Preupgrade Assistant is unable to detect.

1.1.4. Upgrade your system

After you have corrected all issues reported by the Preupgrade Assistant, you are ready to use the Red Hat Upgrade Tool to upgrade your system.

Important

Running the Red Hat Upgrade tool requires you to run the Preupgrade Assistant tool as a pre-requisite. If you try to run Red Hat Upgrade on your system without first running the Preupgrade Assistant, it will exit with the following error:
preupgrade-assistant has not been run

Warning

Test this process on a non-production system before you perform it on any production system.
  1. Install the tool

    # yum -y install redhat-upgrade-tool
  2. Disable active repositories

    # yum -y install yum-utils
    # yum-config-manager --disable \*
  3. Perform the upgrade

    The upgrade process requires access to Red Hat Enterprise Linux  7 packages. You can specify the location of a repository on the network or on a mounted device, or an ISO image, as shown below.
    # redhat-upgrade-tool --network <latest_RHEL_7> --instrepo repo_location
    # redhat-upgrade-tool --device device_path
    # redhat-upgrade-tool --iso iso_path
    Some packages that were in the Base package group in Red Hat Enterprise Linux 6 are no longer part of that group in Red Hat Enterprise Linux 7. You may need to configure additional repositories in order to upgrade these packages correctly.
    Refer to https://access.redhat.com/site/solutions/912213 to enable the Extras repository on the yum repository system. Then see https://access.redhat.com/site/solutions/9892 to set up a repository that you can use during your upgrade. The upgrade command for this use case would look similar to the following.
    # redhat-upgrade-tool --addrepo optional=http://host name/path/to/repo
    Some packages are not reinstalled during the upgrade process because they have no functionally equivalent replacements in Red Hat Enterprise Linux 7. Red Hat does not provide any support for these packages. To remove these packages at the end of the upgrade process, enter the following command:
    # redhat-upgrade-tool --cleanup-post
  4. Reboot

    When prompted, reboot the system.
  5. Wait for upgrade to complete

    After your system reboots, upgrade can take several minutes or several hours, depending on the number of packages to install.
  6. Perform post-upgrade tasks

    Manually perform any post-upgrade tasks described in the Preupgrade Assistant assessment result. See Section 1.1.3.3, “Viewing results and correcting errors” for details.
  7. Check system status

    Check that your system's subscription details have been updated as part of the upgrade process.
    # cat /etc/redhat-release
    Red Hat Enterprise Linux Server release 7.4
    # yum repolist
    Loaded plugins: product-id, subscription-manager
    repo id        repo name                                    status
    rhel-7-rpms    Red Hat Enterprise Linux 7 Server (RPMs)     4,323
    If your repolist did not update correctly, perform the following commands:
    # subscription-manager remove --all
    # subscription-manager unregister
    # subscription-manager register
    # subscription-manager attach --pool=poolID
    # subscription-manager repos --enable=repoID
  8. Update all packages

    Ensure that all packages are up to date by running the following:
    # yum upgrade -y
    # reboot