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 RHEL by replacing the existing operating system.

Note: This procedure is not applicable for upgrading Amazon Web Services(AWS) instances or Amazon Machine Image.

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

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

• All Server editions (except x86): All server editions (except x86) of RHEL 6 can be upgraded with this procedure. Upgrades of RHEL Workstation and Desktop systems are not supported. Upgrades for the POWER architecture are supported. See the table above. Upgrades from the 32-bit architecture are 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 the table below.

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

The upgrade procedure consists of the following basic steps:

1. Prepare the system
   Update the system to the latest minor version of RHEL 6 and install the required tools.
2. Perform the system assessment
   Let the Preupgrade Assistant assess the system to identify possible upgrade issues before performing the actual upgrade. No changes are made to the system and you can repeat this step until you deal with all issues.
3. Perform the upgrade
   Make sure your system is backed up and use the Red Hat Upgrade Tool to perform the upgrade.
4. Provide the feedback
   Let Red Hat know in case you encounter any problems.

Step 1: Prepare the system

1. Get the latest packages
   To make sure you run the latest minor version of Red Hat Enterprise Linux and have the latest packages, register and subscribe the system. Then, type:

   # yum update -y
   # reboot
   

2. Enable the Extras repository
   Enable the repository that contains the preupgrade-assistant, preupgrade-assistant-ui, preupgrade-assistant-el6toel7, preupgrade-assistant-el6toel7-data and redhat-upgrade-tool packages. The repository can be subscribed either through RHN Classic when connecting to a Red Hat Satellite Server, or through Red Hat Subscription Management when connecting to CDN:

   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 

3. Install the required packages
   To install the packages required for the upgrade, type:

   # yum -y install preupgrade-assistant preupgrade-assistant-ui preupgrade-assistant-el6toel7 redhat-upgrade-tool
   

Step 2: Perform the system assessment

The Preupgrade Assistant (the preupg command) lets you assess your system for any 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 determine 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 the 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.

The 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 assessment result.

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

• Leaves your system unchanged except for storing information or logs. It does not 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.

With the Preupgrade Assistant packages installed, you have the option of reviewing the system assessment results locally on the assessed system, or of submitting the report over the network to a remote server that may gather results from multiple systems. These two options are described below.

Option 1: Run the Preupgrade Assistant to view the report locally

1. Run the preupg command to perform the assessment of the system

   # preupg    With no options, produces result.html and tar.gz results files
   The Preupgrade Assistant is a diagnostics tool 
   and does not perform the actual upgrade.
   Do you want to continue? [Y/n]
   y
   Gathering logs used by the 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      |
   --------------------------------------------------------------------------------------------------------
   The tarball with results is stored in '/root/preupgrade-results/preupg_results-170629152543.tar.gz' .
   The latest assessment is stored in the '/root/preupgrade' directory.
   Summary information:
   We have found some potential risks.
   Read the full report file '/root/preupgrade/result.html' for more details.
   Please ensure you have backed up your system and/or data 
   before doing a system upgrade to prevent loss of data in 
   case the upgrade fails and full re-install of the system 
   from installation media is needed.
   Upload results to UI by the command:
   e.g. preupg -u http://example.com:8099/submit/ -r /root/preupgrade-results/preupg_results-170629152543.tar.gz .
   

2. View the assessment result
   When the Preupgrade Assistant scans your system, each performed test is printed to the command line standard output, followed by its result. The tool also produces an assessment report file with detailed information.

   • Command line: The result keyword of each test and the assessment summary are displayed on the screen. Scroll back through the results to get a sense of how the assessment finished. You can see the result keywords only, open the assessment HTML report for more details.

   • Assessment report file: The /root/preupgrade/result.html file can be opened with any Web browser. An example of viewing the file using a Firefox browser:
     # firefox file:///root/preupgrade/result.html

3. Review each test result
   Each of the dozens of tests performed during the assessment has its result keyword. A table listing all the possible test result keywords together with their explanation follows:

   Result keyword	Explanation
   PASS	Everything is fine. You should be able to proceed to the upgrade when all exit codes are listed as PASS.
   FAIL	Extreme upgrade risk. In-place upgrade is not possible.
   NEEDS_ACTION	High upgrade risk. Some administrator action is needed before running the Red Hat Upgrade Tool.
   NEEDS_INSPECTION	Lower or medium risks. This exit code does not necessarily mean the upgrade will fail, but it might result in a system that is not fully functional. Some parts of the system need to be checked and, if needed, fixed by the administrator.
   FIXED	Changes required for the upgrade were fixed automatically. You do not need to review them further.
   INFORMATIONAL	Useful, but not critical, information.
   NOT_APPLICABLE	The package you asked to test is not on your system.
   ERROR	This usually indicates errors in the tools themselves. Report this type of problem to Red Hat Support.

4. View the README file
   There is also a README file in the output directory (/root/preupgrade/). See the file for more information about the output directory structure, exit codes, and risk explanations associated with the preupg tool.

5. Fix found issues
   Resolve the issues found by the Preupgrade Assistant during the assessment. There is a Solution text for each issue in the report, which should help you resolve the issue. Then, run the assessment again, and if there are no new issues to be resolved, continue with Step 3 to upgrade the system.

Option 2: Run the Preupgrade Assistant to view the report remotely

If you have installed the preupgrade-assistant-ui package, you can interact with the Preupgrade Assistant browser-based interface, which is able to collect the assessment reports from multiple systems and provides convenient filtering of the results. Because the upgrade procedure does not support upgrading the GNOME desktop, this procedure gives you a way to display the Preupgrade Assistant results on a remote GUI desktop.

WARNING: Installing and using the Preupgrade Assistant Web UI 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 the data about your system to the network, or if you want to avoid adding content to the system you are upgrading. A safer way to view the Preupgrade Assistant assessment output graphically is to copy the result.html file to a remote system and open it in a Web browser there.

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

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

   # yum -y install httpd
   

2. Configure the conf.d file
   By default, the Preupgrade Assistant Web UI 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:

   # cd /etc/httpd/conf.d
   # cp 99-preup-httpd.conf.public 99-preup-httpd.conf
   

3. Edit the new .conf file
   The 99-preup-httpd.conf file, which you created in the previous step, will make the Preupgrade Assistant 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 the 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 Assistant Web 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 to load the new configuration

   # service httpd restart
   

6. Access the Preupgrade Assistant Web UI from a Web browser
   From a Web browser on another system, access the Preupgrade Assistant Web UI service by using either an IP address (for example http://192.168.99.1:8099) or a hostname (for example http://preupg-ui.example.com:8099).

7. Add Web UI authentication information
   The first time you access the Preupgrade Assistant Web UI, you are offered to add a user account, which can be used to gain access to the service, or disable the authentication feature.

   • With authentication
     Use either the existing user account or create a new one. If you select "Submit" to create a new user, it will automatically enable the authentication system if it has been disabled. Later, if you would like to edit users, navigate to the User Management tab in the UI.
   • No authentication
     If you do not want to authenticate, click on "Disable Authentication" and you can start using the graphical Interface.

8. Run the preupg command
   Return back to the system you plan to upgrade. To perform the system assessment with an automatic submission of the result to the Preupgrade Assistant Web UI server, type:

   # preupg -u http://localhost:8099/submit/
   The Preupgrade Assistant is a diagnostics tool 
   and does not perform the actual upgrade.
   Do you want to continue? [Y/n]
   y
   Gathering logs used by the Preupgrade Assistant:
   All installed packages : 01/10 ...finished ...
     ...
   Report submitted successfully. You can inspect it at http://localhost:8099/1/detail/
   

9. View the assessment report from the Web UI
   Return to your Web browser on the remote system and access the Web UI again or just reload the page. An example of the Preupgrade Assistant Web UI:

   

10. Fix the reported issues
    In the Web UI, find and expand the correct assessment report. Go through each item in the report and perform changes necessary to fix the reported issues. Then run preupg to assess the system again, upload the report to the Web UI, and if there are no new issues to resolve, proceed to Step 3.

Step 3: Perform the upgrade

With the Preupgrade Assistant assessment completed and all issues addressed, the next step is to use the Red Hat Upgrade Tool to perform the actual system upgrade.

IMPORTANT: Running the Red Hat Upgrade Tool requires you to run the Preupgrade Assistant tool as a prerequisite. If you try to run the Red Hat Upgrade Tool on your system without running the Preupgrade Assistant first, it will exit with the following error: preupgrade-assistant has not been run. This error is possible to be overridden by the --force option, but in that case the upgraded system will not be supported.

1. Back up the system
   Before performing the upgrade by using the Red Hat Upgrade Tool on a system that is in any way important to you, make sure you back up all of your data in order to avoid potential data loss.

2. Test first
   Do not attempt to perform an upgrade of a production system. Clone your system first and test the upgrade procedure in a safe environment.

3. Convert to Subscription Management
   Red Hat Enterprise Linux 7 requires Red Hat Subscription Management (RHSM) tools, rather than RHN Classic tools. 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?), and then register it by using the subscription-manager command. See Get Started with Red Hat Subscription Management for more information. You can also use an automated method of migrating from RHN to RHSM.

4. Run redhat-upgrade-tool to download the packages needed to upgrade to Red Hat Enterprise Linux 7 and prepare the package installation. You can use several options to indicate the location of the Red Hat Enterprise Linux 7 packages:

   • Installation repository
     To indicate the location of a repository that holds Red Hat Enterprise Linux 7 packages, use the --instrepo option. You need to create such a repository by yourself, as Red Hat does not provide that. In this example, we use an FTP server, on which the contents of the the latest RHEL 7 DVD is copied to a rhel7/ directory. You can also use an HTTP or HTTPS site that contains the latest Red Hat Enterprise Linux 7 packages.

   # redhat-upgrade-tool --network <the-latest-rhel-7-minor-version> --instrepo ftp://ftp.example.com/pub/rhel7/
   example:
   # redhat-upgrade-tool --network 7.3 --instrepo ftp://ftp.example.com/pub/rhel7/ 

   If an invalid Red Hat Enterprise Linux 7 minor version is specified, upgrade will fail after attempting to contact non-existing repositories.

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

   # redhat-upgrade-tool --device /dev/sdb
   

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

   • ISO image
     To upgrade the 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
   

   NOTE: For the upgrade to work properly, you might need an 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 repository, you can install a separate RHEL 7 system to act as a yum repository to serve the packages you need over FTP or HTTP. Use createrepo or reposync to create a local repository for updates to set up a repository that you can use during your upgrade. To tell Red Hat Upgrade Tool about the additional repository, use --addrepo. The command may look as follows:

   # redhat-upgrade-tool --device /dev/sdb --addrepo optional=http://host/repo
   

5. Reboot
   To complete the installation, you need to reboot the system. After rebooting, depending on how many packages are being upgraded, it could take some time to complete. If everything goes as expected, the system will reboot to Red Hat Enterprise Linux 7, and you can begin checking that the system works properly.

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

7. 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 that the system was properly upgraded and subscribed as a RHEL 7 system, type:

   # 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)
   

8. Fix the 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
   

9. Run yum update
   If the upgrade appears to be successful, upgrade all your new RHEL 7 packages to their latest version:

   # yum update -y
   # reboot
   

Step 4: Provide the feedback

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

Feel free to submit a debug log, which is located on the upgraded system in the /var/log/upgrade.log file.