CentOS Upgrade Tool

1. Location of the Tool

The tool is currently available from the testing repository:

http://dev.centos.org/centos/6/upg/x86_64/Packages/

DO NOT USE this tool. Warning: use of this tool is currently BROKEN as several system-critical packages are of a higher version number in CentOS 6.7 than they are in CentOS 7 so those do not get upgraded correctly. This renders yum and several other system tools non-functional.

1.1. How to Currently Obtain the Tool

Create a Repo file in /etc/yum.repos.d/, named something like upgradetool.repo

Add the following lines to the repo file:

[upg]
name=CentOS-$releasever - Upgrade Tool
baseurl=http://dev.centos.org/centos/6/upg/x86_64/
gpgcheck=1
enabled=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-6

This command will then get the RPMs installed to run an upgrade:

yum install redhat-upgrade-tool preupgrade-assistant-contents

Once we do some more testing and move this to the Extras repository, then you will only need to do the yum install command and not create a repo file. These instructions will be changed when the release happens and the tool is no longer in testing.

2. Preupgrade Assistant Purpose

Preupgrade assistant performs an assessment of the system from the "upgradeability" point of view. Such analysis includes checking for removed packages, packages replaced by partially incompatible packages, changes in libraries, users and groups and various services. A report of this analysis can help the administrator with the in-place upgrade - by identifying potential troubles and by mitigating some of the incompatibilities. Data gathered by the preupgrade assistant can be used for the "cloning" of the system - a new, clean installation of the system, as close as possible to the old CentOS setup. In addition, it provides some postupgrade scripts which are supposed to finish the migration after the installation of the CentOS-7 system.

As the preupgrade assistant doesn't directly modify the assessed system (except storing information/logs), it is safe to use it on any configuration. As the contents are not yet complete, successful preupgrade assistant analysis doesn't necessarily mean that the in-place upgrade via centos-upgrade-tool will succeed.

3. Preupgrade Assistant Usage

At the moment, only a CLI interface and limited functionality is available.

Usage is simple. Just follow these steps:

  1. Run "preupg -l" command - it lists all available contents for preupgrade-assistant (as the system is based on a plugin, there may be modules from different sources in the future). If nothing is shown, install the preupgrade-assistant-contents package.
  2. If you have CentOS6_7 content available, run the command preupg -s CentOS6_7

  3. Wait until the analysis finishes (it can take several minutes)
  4. Review the report stored as /root/preupgrade/result.html (and possibly files stored at /root/preupgrade). Especially check for inplace upgrade risks (described further in this document)

4. /root/preupgrade File and Directory Structure

This directory contains the data from the last preupgrade assistant run.

Files:

Directories:

5. An Explanation of Possible Check Exit Codes

Every single plugin has its own exit code. Administrators need to check at least those with FAIL results before doing the inplace upgrade. Results marked FIXED should be checked after the inplace upgrade - to finish the CentOS-7 migration properly.

The possible exit codes are:

6. In Place Upgrade Risk Explanations

There are several levels of inplace upgrade risks. Any level higher than "slight" means you will get not a 100% functional upgraded system, although the inplace upgrade tool "centos-upgrade-tool" may pass.

The available risk assessment levels are:

7. How to Upgrade After Reviewing the Results

Once you are ready to upgrade (you have mitigated all issues you care to mitigate, etc.), you first need to import the CentOS-7 RPM key with this command:

rpm --import http://mirror.centos.org/centos/RPM-GPG-KEY-CentOS-7

Then run the following command to upgrade:

centos-upgrade-tool-cli --network 7 --instrepo=http://mirror.centos.org/centos/7/os/x86_64/

Then reboot.

See man centos-upgrade-tool for more information on all options available for the tool.

NOTE: Use of this tool is at your own risk and is not the best method for upgrades. Make sure you have backups before you actually perform an upgrade. If it breaks, you get to keep both halves!

8. Known Issues When Upgrading

example output:

INPLACERISK: EXTREME: You have GNOME Desktop Environment session as an option in your X11 session manager. GNOME Desktop 
Environment as a part of the yum group 'Desktop' underwent serious redesign in its user interface as well as underlying 
technologies in CentOS-7.

example output:

INPLACERISK: EXTREME: Some partitions are crypted. If it is a system partition then in-place upgrade is not possible.

As we get more specific examples of issues, we will update this page.

TipsAndTricks/CentOSUpgradeTool (last edited 2015-11-24 23:46:15 by TrevorHemsley)