Upgrade CentOS/RHEL

Howto Upgrade a CentOS/RHEL Server


Red Hat has now provided a path to upgrading from an older release of an operating system to the latest version. This tool is known as the "redhat-upgrade-tool". This tool is now available for CentOS too. Below is a guide to installing and using the tool. Part of the new process also provides a pre-upgrade tool assistant that will try to identify problems or issues that may arise from the upgrade process. Although the tool can be used to aid in the upgrade process; if your server has a lot of third party packages installed and customization, you may need to consult with the package provider for any configuration changes that may be required to be carried out. This tool is primarily aimed at a server that is not using a graphical environment (Gnome, KDE etc..). Before proceeding with upgrade process, you should make a full backup of your current system.

Note: This upgrade process is New and currently not recommended as best practice!

In the following example, I am using a minimal build CentOS 6.5 Server installed within Oracle's virtual box software.

Create a repo for the upgrade tool

To download the tools required, we will need to create a repo with the information below. In this example we have called the repo "upgradetool.repo". The repo file should be created in the following path /etc/yum.repos.d/:

name=CentOS-$releasever - Upgrade Tool

Once the above lines have been added, save this file. Your file should now match the output below:

[root@kicks03 ~]# cat /etc/yum.repos.d/upgradetool.repo
name=CentOS-$releasever - Upgrade Tool

You can run the command: yum repolist. This command should now display all repos available to your system including the one just added.

Install upgrade tool and preupgrade assistant packages

The following "yum" command now needs to be issued to install the necessary packages and any dependencies:

Command Issued: yum install redhat-upgrade-tool preupgrade-assistant-contents

[root@kicks03 ~]# yum install redhat-upgrade-tool preupgrade-assistant-contents

Running the Preupgrade Assistant

The Preupgrade Assistant runs an assessment of the upgradability of your server. Various checks against currently installed packages are carried out. A report is generated indicating where problems may be found. This should help the administrator mitigate many of the possible issues. The preupgrade assistant can be run numerous times on any server as it will not make any changes to a system.

Currently the preupgrade assistant can only be run from the command line as follows:

The command "preupg -l" lists all available contents for the preupgrade-assistant. If you do not see any output back from this command, then you may have not installed the "preupgrade-assistant-contents" package.
This can be installed with the command: "yum install preupgrade-assistant-contents"

To generate the report issue the following command: preupg :

[root@kicks03 ~]# preupg

You will see an informational message similar to the one below:

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

Reply "y" for yes to continue with the report generation. This process can take several minutes depending on the system it is being run on.

NOTE: If you have not taken a full backup of your current system. It is Highly recommended that you do so now!

Analysing the report

The reports generated can be found in the following locations: /root/preupgrade/

[root@kicks03 /]# cd /root/preupgrade
[root@kicks03 preupgrade]# ls -l
total 1812
drwxr-xr-x. 16 root root    4096 Oct  5 18:53 CentOS6_7
drwxr-xr-x.  3 root root    4096 Oct  5 18:53 cleanconf
drwxr-xr-x.  2 root root    4096 Oct  5 18:53 common
drwxr-xr-x.  5 root root    4096 Oct  5 18:53 dirtyconf
drwxr-xr-x.  2 root root    4096 Oct  5 18:53 etc
drwxr-xr-x.  2 root root    4096 Oct  5 18:54 kickstart
drwxr-xr-x. 11 root root    4096 Oct  5 18:54 postupgrade.d
-rw-r--r--.  1 root root 1300263 Oct  5 18:54 preupg_results-141005185424.tar.gz
-rw-r--r--.  1 root root    6339 Oct  5 18:53 README
-rw-r--r--.  1 root root   86087 Oct  5 18:54 result.html
-rw-r--r--.  1 root root  417934 Oct  5 18:54 result.xml
-rw-r--r--.  1 root root     166 Oct  5 19:10 upgrade.conf

result.html : The result file contains a migration assessment report. This file can be viewed best in a browser.
result.xml : This file is the same as the above however it is in a machine readable format.
README : Readme file.
results.tar.gz - This compressed Tar Ball file contains all the files in the directory "/root/preupgrade".


cleanconf: Directory with all user-modified configuration files, which were checked for their compatibility by the preupgrade-assistant. These files can be safely used on a CentOS-7 system (some of these files may need postupgrade.d scripts execution)

dirtyconf: Directory with all user-modified configuration files, which were not checked for their compatibility by the preupgrade-assistant. These may require admin review after the CentOS-7 installation/upgrade.

kickstart: Directory which contains various files useful for generating a kickstart file for cloning this system. Some of the files in this directory may give administrators the necessary guidance in what was not handled by the centos-upgrade-tool (and will need some additional actions). See the README file in the kickstart directory for the file descriptions.

CentOS6_7: Just "debugging" directory - will be removed later. Ignore, unless you'll see some "Error" plugin exit status.

postupgrade.d: Contains various scripts which are supposed to be executed AFTER the upgrade to CentOS-7. These scripts should NEVER be used on a CentOS-6 system.

If you need to move the "result.html" file to a PC or another system that has a browser, you can run a command similar to the one below:

scp root@ .

john@ubuntu01-pc:~$ scp root@ .
root@'s password: 
result.html                                   100%   84KB  84.1KB/s   00:00 

The above "scp" command was run on a local PC. The file was then copied from the CentOS server to the current location.
"" is the IP address of the CentOS server that is being upgraded. The "." (dot) after the filename "result.html" specifies to copy the file to the current location.

When viewed with a browser, you will see output similar to the image below:

redhat-upgrade-tool result.html report

The above only shows the upper section of the "html" report. From the actual report, you can click on any of the subject titles for a full overview. There are several exit codes that can be generated within the report. These are as follows:

Understanding the Exit Codes

The possible exit codes are as follows:

PASS = Everything is fine, No incompatibility/issue detected by this checker.
FAIL = Some incompatibility/issue that needs to be reviewed by the admin was detected. FAIL does not necessarily mean that the in-place upgrade will fail, but may result in a not 100% functional system.
FIXED = Some incompatibility was detected, but the preupgrade-assistant was able to find an automated solution. Some of the fixes may require running postupgrade.d scripts after the upgrade. Fixed configs are available in the "/root/preupgrade/cleanconf" directory. "preupgrade-assistant" does not handle the fixes automatically at the moment.
INFORMATIONAL = "Nice to have" information for admins (e.g. removed options in some common tools which may cause malfunctions of their scripts)
NOT_APPLICABLE = Package which should be tested, but the check is not installed on the system (test therefore doesn't make sense).
ERROR = Shouldn't occur, does usually mean error in the preupgrade-assistant framework. All such errors should be reported to the Red Hat preupgrade-assistant team.

Risk Explanation

There are several levels of in-place upgrade risks. The available risk assessment levels as per the Centos Wiki are:

None: Default. It can be used as an indicator for some checks. It is not necessary to enter these values.
Slight: We assessed this field and have not found any issues. However, there is still some risk that not all variants have been covered.
Medium: It is likely that the area causes a problem in case of the in-place upgrade. It needs to be checked by the administrator after the in-place upgrade and after the system has been monitored for some time.
High: The in-place upgrade can't be used safely without the administrator's assistance. This typically involves some known broken scenarios or existing 3rd party packages. After the administrator manually fixes the issue, it may be possible to perform the in-place upgrade, but it is not recommended.
Extreme: We found an incompatibility which makes the in-place upgrade impossible. It is recommended to install a new system with the help of the preupgrade-assistant remediations.

Starting the Upgrade Process

Once any issues have been sorted that were found in the generated report from the preupgrade assistant, you may initiate the upgrade process. (Remember to make a backup if you haven't already done so).

First, import the CENTOS 7 GPG key. This is achieved by issuing the following command:

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

[root@kicks03 ~]# rpm --import http://mirror.centos.org/centos/RPM-GPG-KEY-CentOS-7

Now run the Upgrade Command:

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

[root@kicks03 ~]# centos-upgrade-tool-cli --network 7 --instrepo=http://mirror.centos.org/centos/7/os/x86_64/

After several minutes, you should see a message issued similar to the message below. Indicating that a reboot is required to initiate the "upgrade" process. (You can reboot the server by issuing the "shutdown -r now" command):

testing upgrade transaction
rpm transaction 100% [=========================================================]
rpm install 100% [=============================================================]
setting up system for upgrade
Finished. Reboot to start upgrade.

The upgrade process will now start. You may see the system reboot several times depending on the packages you currently have installed.

Progress is indicated during the upgrade:

redhat-upgrade-tool Progress indicator

First Login

After the upgrade process has completed, you should check that the OS reports the correct OS level and you have the correct kernel level. It is advisable to check all log files and error logs for any possible issues that may not have been detected.

[root@kicks03 ~]# cat /etc/redhat-release 
CentOS Linux release 7.0.1406 (Core) 
[root@kicks03 ~]# uname -a
Linux kicks03 3.10.0-123.8.1.el7.x86_64 #1 SMP Mon Sep 22 19:06:58 UTC 2014 x86_64 x86_64 x86_64 GNU/Linux