How do I upgrade from Red Hat Enterprise Linux 6 to Red Hat Enterprise Linux 7?

Solution Verified - Updated -

Environment

  • Red Hat Enterprise Linux 6.x to Red Hat Enterprise Linux 7
Product Variant x86 Architecture x86_64 Architecture IBM Power IBM z Systems
Desktop Edition Not supported Not supported N/A N/A
Workstation Edition Not supported Not supported N/A N/A
Server Edition Not supported Supported Supported[1] Supported[2]
HPC Compute Node Not supported Supported N/A N/A
Server running CloudForms software N/A Not supported N/A N/A

[1] Red Hat Enterprise Linux for Power, big endian
[2]Red Hat Enterprise Linux for IBM z Systems

Issue

  • How do I do in-place upgrading from the latest Red Hat Enterprise Linux 6 to the latest Red Hat Enterprise Linux 7?
  • How do I use the preupgrade assistant and redhat-upgrade-tool to run a RHEL6 to RHEL7 upgrade?

Resolution

Overview

Red Hat Enterprise Linux 7 (RHEL 7) is the first major release of RHEL to allow in-place upgrades from the previous RHEL major release (RHEL 6). An in-place upgrade offers a way of upgrading a system to a new major release of Red Hat Enterprise Linux by replacing the existing operating system.

This RHEL 6 to RHEL 7 upgrade procedure is fully supported if your Red Hat Enterprise Linux system meets the following criteria:

  • Latest Red Hat Enterprise Linux 6: Before upgrading to the latest RHEL 7, you must start with RHEL 6 and update your system to have the latest RHEL 6 packages installed. (This is covered in the procedure below.)

  • All Server editions (except x86): All server editions (except x86) of Red Hat Enterprise Linux 6 can be upgraded with this procedure. Upgrades of RHEL Workstation and Desktop systems are not supported. Upgrades for the POWER architecture is supported. SEE TABLE ABOVE. Upgrade from 32-bit architecture is not supported.

  • Limited package groups: The upgrade process handles only the following package groups and packages: Minimal (@minimal), Base (@base), Web Server (@web-server), DHCP Server, File Server (@nfs-server), and Print Server (@print-server). Although upgrades of other packages and groups are not supported, in some cases, packages can be uninstalled from the RHEL 6 system and reinstalled on the upgraded RHEL 7 system without a problem. SEE TABLE BELOW.

The supported use cases for upgrading RHEL 6 to RHEL 7:

Supported Unsupported
Source to Upgrade The latest RHEL-6.X RHEL 6.4 and earlier
File Systems Like-file system upgrades
For example ext3 to ext3, ext4 to ext4, xfs to xfs
Unlike-file system upgrades
For example ext4 to xfs
GNOME, KDE None All GNOME, KDE installs
Packages/Groups Minimal (@minimal)
Base (@base)
Web Server (@web-server)
DHCP Server
File Server (@nfs-server)
Print Server
All others
Virtualization KVM, VMWare Microsoft Hyper-V (coming soon)
Red Hat Software Collections Using tested process All others
High Availability None All

The upgrade procedure consists of the following basic steps:

  1. Prepare for Upgrade: Make sure your system is backed up and up to date before beginning the preupgrade.
  2. Install the Preupgrade Assistant: Enable the required repositories and install the preupgrade packages.
  3. Run the Preupgrade Assistant: Check your system for upgrade issues before running the actual upgrade. No changes are made to your system and you can repeat this step until all issues are dealt with.
  4. Run the Upgrade: Perform the actual upgrade.
  5. Provide Feedback: Create a debug log to send to Red Hat in case there are problems.

Step 1: Prepare for Upgrade

A major operating system upgrade should not be taken lightly. Before starting the upgrade procedure on a system that is in any way important to you, consider the following:

  1. Test first: Do not attempt to perform an upgrade on a production system. You should first clone your system and test the upgrade procedure in a safe environment. Before using the Red Hat Upgrade Tool, make sure you back up all of your data in order to avoid potential data loss.

  2. Convert to Subscription Management: Red Hat Enterprise Linux 7 requires Subscription Management tools (such as subscription-manager) rather than RHN Classic tools (such as rhn_register). If your Red Hat Enterprise Linux 6 system is currently registered using RHN Classic tools, you can unregister it (see How do I delete System Profiles in RHN Classic?), then register it using the subscription-manager command (see Get Started with Red Hat Subscription Management). If you'd like a more automated method, use the included migration script.

  3. Get the latest packages: To make sure you have the latest packages, register and subscribe the system, then type the following:

    # yum update -y
    # reboot
    
  4. Consider other repositories: For the upgrade to work properly, you may need access to software repositories beyond what is offered from the basic packages on the RHEL 7 DVD. In particular, the Extras repository in RHEL 7 contains some packages (mostly related to software development) that were in the RHEL 6 base system, but are not on the DVD.

    If you know that your upgrade requires packages (to meet dependencies) that are not in the RHEL 7 base repo, you can install a separate RHEL 7 system to act as a yum repository to serve the packages you need over FTP or HTTP. Refer to How can I subscribe to the new Extras channel/repo? to enable the Extras repository on the yum repository system and Use createrepo or reposync to create a local repository for updates to set up a repository that you can use during your upgrade. The command line for doing the upgrade (near the end of this procedure) would look something like the following: redhat-upgrade-tool --device /dev/sdb --addrepo optional=http://host/repo

Step 2: Install the Preupgrade Assistant

The Preupgrade Assistant (preupg command) lets you check for potential problems you might encounter with a Red Hat Enterprise Linux 6 to Red Hat Enterprise Linux 7 upgrade before any changes to your system are made. This will help you assess your chances of successfully upgrading to the latest Red Hat Enterprise Linux 7 before the actual upgrade process begins.

NOTE: You can (and should) run Preupgrade Assistant multiple times to address anything that could cause problems before running the actual upgrade. The Preupgrade Assistant will not harm your installed system. However, once you perform an in-place upgrade on your system, it is not possible to get the previous working system back.

Preupgrade Assistant does the following:

  • Assesses the system for possible in-place upgrade limitations, such as package removals, incompatible obsoletes, name changes, or deficiencies in some configuration file compatibilities.

  • Provides a report with the analysis results.

  • Provides data which could be used for "cloning" the system, if the in-place upgrade is not suitable.

  • Provides some postupgrade scripts to finish more complex issues after the in-place upgrade.

  • Leaves your system unchanged (except for storing information/logs, it doesn't modify the assessed system).

Because the Preupgrade Assistant is based on a module system, new checks and upgrade actions can be added relatively easily. So you can expect the tool to improve over time.

To install, configure, and run the Preupgrade Assistant, from the the latest Red Hat Enterprise Linux 6.x system that you want to upgrade do the following steps:

  1. Enable preupgrade repositories: Enable the repository that contains the preupgrade-assistant, preupgrade-assistant-ui, preupgrade-assistant-el6toel7 and preupgrade-assistant-el6toel7-data packages. The repositories are different, depending on whether you are connecting to a Red Hat Satellite Server or Subscription Management in the Red Hat portal:

    RHN Classic (Satellite):

    # rhn-channel --add --channel rhel-x86_64-server-extras-6 
    # rhn-channel --add --channel rhel-x86_64-server-optional-6 

    Red Hat Subscription Management

    # subscription-manager repos --enable rhel-6-server-extras-rpms 
    # subscription-manager repos --enable rhel-6-server-optional-rpms 
  2. Install the preupgrade packages: Preupgrade packages include preupgrade-assistant (contains the preupg command), preupgrade-assistant-ui (contains the optional web-based interface), and preupgrade-assistant-el6toel7 (contains modules that contain different tests). To install them, type the following:

    # yum -y install preupgrade-assistant preupgrade-assistant-ui preupgrade-assistant-el6toel7
    

Step 3: Run the Preupgrade Assistant

With the preupgrade packages installed, you have the choice of running the Preupgrade Assistant to view the results locally or to serve results over the network (from a local httpd server). Those two choices are described below.

Choice 1: Run Preupgrade Assistant to View Locally

To run the preupg command so that the output is displayed on the screen and output to local files on the system you want to upgrade, follow the procedure below:

  1. Run the preupg command: Run the preupg command to start the Preupgrade Assistant as follows:

    # preupg    With no options, produces result.html and tar.gz results files
    Preupg tool doesn't do the actual upgrade.
    Please ensure you have backed up your system and/or data in the event of a failed upgrade
     that would require a full re-install of the system from installation media.
    Do you want to continue? y/n  
      y
    Gathering logs used by preupgrade assistant:
    All installed packages : 01/10 ...finished (time 00:01s)
       ...
    |Removed rpms                                                                       |needs_inspection  |
    |Content for enabling and disabling services based on RHEL 6 system                 |needs_inspection  |
    |Python 2.7.5                                                                       |needs_inspection  |
    |Check for usage of dangerous range of UID/GIDs                                     |needs_inspection  |
    |Packages not signed by Red Hat                                                     |needs_action      |
    --------------------------------------------------------------------------------------------------------
    Tarball with results is stored here /root/preupgrade-results/preupg_results-140528114006.tar.gz .
    The latest assessment is stored in directory /root/preupgrade .
    Summary information:
    We found some potential in-place upgrade risks.
    Read the file /root/preupgrade/result.html for more details.
    Upload results to UI by command:
    e.g. preupg -u http://127.0.0.1:8099/submit/ -r /root/preupgrade-results/preupg_results-*.tar.gz .
    

    Once the preupg process is done, you have several choices for viewing the results of the process.

  2. View preup results: As preupg scans your system it lists each test it performs on the screen, followed by an exit code that describes the test's results. It also produces results files you can review in the following ways:

    preupg command line: Exit codes and results appear on the screen. You can just scroll back through those results to get a sense of how well each test succeeded. This only gives you exit codes, however, and not descriptions of each issue.

    result.html: The /root/preupgrade/result.html file can be opened in any Web browser. With no GUI, you can open the file with the links command or you could copy the file to another system that has a graphical browser to view the file.

  3. Check exit codes: The Result shown for each test includes an exit code. Possible exit codes for the different plug-ins used by preupg include:

    PASS
    Means everything is fine. You should be able to proceed to the upgrade when all exit codes are listed as PASS.

    FAIL
    Extreme upgrade risks. In-place upgrade is not possible.

    NEEDS_ACTION
    High upgrade risk. Some action is needed from the administrator before running Red Hat Upgrade.

    NEEDS_INSPECTION
    Medium and lower risks. This exit code does not necessarily mean an upgrade will fail, but may result in a system that is not fully functional. Some parts need to be checked and, if needed, fixed by the administrator.

    FIXED
    Indicates that something was fixed automatically. You should not need to review it further.

    INFORMATIONAL
    Useful, but not critical, information.

    NOT_APPLICABLE
    The package you asked to test is not on the system.

    ERROR
    This usually indicates errors in the tools themselves. Report this type of problem to Red Hat Support.

  4. View the results: As noted earlier, an HTML file containing a report of the results of preupg is stored on the local system. You can view that file using any Web browser. With no desktop installed, you could use the links command (links /root/preupgrade/result.html) or copy the file to a system that has a graphical Web browser available (such as Firefox). Here is an example of how you could view that file using firefox:

    # firefox file:///root/preupgrade/result.html
    

    The following figure shows an example of the report:

    RHEL 7 Preupgrade Report

    For each Title, click the entry in the Result column. You will be able to see a description of the problem encountered and a description of how to solve it.

  5. View the README file: There is also a README file in the output directory. Refer to that file for more information about the purpose, usage, directory structure, exit codes, and risk explanations associated with the preupg tool.

  6. Make corrections: Correct any errors encountered by the preupg command and run preupg again. Once you feel you have addressed all the issues that come up, you can proceed to the upgrade in Step 4.

Choice 2: Run Preupgrade Assistant to View Remotely

If you installed the preupgrade-assistant-ui package, then you can interact with the Preupgrade Assistant's browser-based interface, which enables easy searching and filtering of the results. Because the upgrade procedure does not support updates of the GNOME desktop, this procedure gives you a way to display the results from the Preupgrade Assistant on a remote, graphical desktop.

WARNING: Using the Preupgrade Assistant Web UI, unlike other ways of using the preupg command, changes the content of the system you are upgrading by adding files to the /etc/httpd/conf.d directory and running an httpd service on that system to serve the content. You should not use this procedure in an environment if you are concerned about exposing data about your system to the network or if you want to avoid adding content to the system you are upgrading. An easier way to view preupg output graphically on a remote system is to copy the result.html file to that system and open it in a Web browser.

Do the following procedure if you want to use the Preupgrade Assistant Web UI to access preupgrade information from a browser over the network:

  1. Install httpd: If it is not already installed on the RHEL 6 system you are upgrading, install the httpd package:

    # yum -y install httpd
    
  2. Configure conf.d file: By default, the preupgrade UI service is only available to the local system (127.0.0.1). To make it available to all network interfaces on the local system (TCP port 8099 by default), type the following:

    # cd /etc/httpd/conf.d
    # mv 99-preup-httpd.conf 99-preup-httpd.conf.private
    # cp 99-preup-httpd.conf.public 99-preup-httpd.conf
    
  3. Edit the new .conf file: As delivered the 99-preup-httpd.conf you just copied will make the preupgrade UI available through an IP address on the host. If you want to access this service using a hostname instead of an IP address, you can also change the "NameVirtualHost" line in this file. For example, the line NameVirtualHost preupg-ui.example.com:8099 could be used to access the service if you had a DNS CNAME record pointing the name preupg-ui.example.com to the system you are upgrading.

  4. Open firewall and SELinux: If you have a firewall running and SELinux in enforcing mode, you can use the following commands to allow access to the port needed by the preupgrade UI service:

    # setsebool httpd_run_preupgrade on
    # iptables -I INPUT -m state --state NEW -p tcp --dport 8099 -j ACCEPT
    
  5. Restart the httpd service: Type the following to have the httpd service start with the new configuration information:

    # service httpd restart
    
  6. Access preupgrade from a Web Browser: From a Web browser on another system (we advise using the latest version of Firefox or Chrome), access the preupgrade Web ui service, using either the IP address (for example, http://192.168.99.1:8099) or hostname (for example, http://preupg-ui.example.com:8099).

  7. Add authentication information: You can either add a user to authenticate or disable authentication to the Web UI.

    • Authenticate: The first time you access the preupgrade Web UI, you are offered the chance to add a user, email address, and password that can be used to gain access to the service, or disable the authentication feature. (Later, if you would like to administer users, navigate to the User Management tab on the UI. You can create, edit and delete user roles there.) If you select "Submit" to create a new user, it will automatically enable the authentication system if it has been disabled.
    • No authentication: If you don't want to authenticate, just click on "Disable Authentication" and you may start using the Graphical Interface.
      Once you determine you have access to the preupgrade Web UI, you can go back to the system you are upgrading to gather and load preupgrade data.
  8. Run the preupg command: To run the preupgrade so that the results are loaded into the preupgrade Web UI, type the following on the system that you are upgrading:

    # preupg -u http://localhost:8099/submit/
    Preup tool doesn't do the actual upgrade.
    Please ensure you have backed up your system ...
    Do you want to continue? y/n y
    Gathering logs used by preupgrade assistant:
    All installed packages : 01/10 ...finished ...
      ...
    Report submitted successfully. You can inspect it at http://localhost:8099/1/detail/
    
  9. View the preupgrade reports: Once the preupg has been run and submitted to the Web UI, return to your Web browser on the remote system and access the Web UI again (or just reload the page. Select the date of the preupgrade run to display the results of that preupgrade. Go through each item by clicking on it and make corrections necessary to fix the problem. An example of the preupgrade Web UI displaying a preupg run is shown here:

    View preupgrade runs in Web ui

  10. Make corrections: Correct any errors encountered by the preupg command and run the preupg to submit the data again. Once you feel you have addressed all the issues that come up, you can proceed to the actual upgrade in Step 4.

Step 4: Run the Upgrade

With the Preupgrade Assistant completed and all issues addressed, the next step is to go to the system you want to upgrade, install the redhat-upgrade-tool package, run the upgrade, and reboot, as described here:

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

  1. Install redhat-upgrade-tool: Run the following command to install the redhat-upgrade-tool package:

    # yum install redhat-upgrade-tool
    
  2. Disable repos (Satellite only): If you have subscribed your system to a Red Hat Satellite 6, the Red Hat Network yum plugin (rhnplugin) enables some repositories that must be turned off before you run the redhat-upgrade-tool command. To disable this plugin, edit the enabled line in the /etc/yum/pluginconf.d/rhnplugin.conf file so it appears as follows:

    enabled = 0
    
    • If system is registered to Satellite 5, do not disable rhnplugin, as rhn is the only registration mechanism available in Satellite 5
    • Only registration mechanism in Satellite 5 is rhn, so no need to disable rhplugin if system registered to Satellite 5
  3. Run redhat-upgrade-tool: To download the packages needed to upgrade to Red Hat Enterprise Linux 7 and prepare for the package installation, you can use several different options to indicate the location of the installation packages.

    • To indicate the location of a repository that holds Red Hat Enterprise Linux 7 packages, use the --instrepo option. (You must create this repository yourself as Red Hat does not provide this.) In this example, we use an FTP site where the contents of the the latest RHEL 7 DVD is copied to a directory called rhel7 on an available FTP server. You can also use an http or https site that contains the latest RHEL 7 packages:
    # redhat-upgrade-tool --network <the-latest-rhel-7-version> --instrepo ftp://ftp.example.com/pub/rhel7/
    

    The version can be any number greater than your current system version. If an invalid version is specified, upgrade fails after
    attempting to contact non-existing repositories.

    • To upgrade your system through installation media mounted on your system, for example from a DVD or USB drive available from the /dev/sdb device, as root run the following command:
    # redhat-upgrade-tool --device /dev/sdb
    

    If this option is specified without a device, the tool scans all currently-mounted removable devices.

    • To upgrade your system using an ISO image, provide the path to the ISO image after the --iso option. For example, if the latest RHEL 7 installation DVD was located at /var/isos/rhel7dvd.iso on the local system, the command would look as follows:
    # redhat-upgrade-tool --iso /var/isos/rhel7dvd.iso
    
  4. Reboot: To complete the installation, you need to reboot the system. After rebooting, depending on how many packages are being upgraded, it could take anywhere from a few minutes to an hour or more to complete. If all goes well, the system will reboot to Red Hat Enterprise Linux 7 and you can begin checking that the system works properly.

  5. Perform post-upgrade tasks: The scripts that have been created by the Preupgrade Assistant for the FIXED items will run automatically after the upgrade. Any other post-upgrade tasks that the administrator should run manually are identified by the Preupgrade Assistant results.

  6. Check the system: If your system had been properly registered and subscribed for RHEL 6, the upgrade process should have automatically resubscribed it for RHEL 7. To make sure the system was properly upgraded and subscribed as a RHEL 7 system, type the following:

    # 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
    # cat /etc/redhat-release
    Red Hat Enterprise Linux Server release 7.0 (Maipo)
    
  7. Fix repolist if necessary: If the repository list was not properly upgraded to RHEL 7, unsubscribe the system, resubscribe it as a RHEL 7 system, and add the repositories you need (all available repositories should be listed in the /etc/yum.repos.d/redhat.repo file).

    # subscription-manager remove --all
    # subscription-manager unregister
    # subscription-manager register
    # subscription-manager attach --pool=poolID
    # subscription-manager repos --enable=repoID
    
  8. Run yum update: If the upgrade appears to be successful, upgrade all your new RHEL 7 packages to the latest version of those packages as follows:

    # yum update -y
    # reboot
    

Step 5: Provide feedback

Please provide feedback to Red Hat related to any problems you encounter during the upgrade process. We would appreciate you entering bug reports or opening support cases so we can address any problems you encounter.

Please feel free to submit a debug log, which is located on the upgraded system in the following file:

/var/log/upgrade.log

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.