RHEL 7 Preupgrade-Assistant Tutorial


One of the new features announced with RHEL 7 is the ability to do an in-place upgrade from RHEL 6. This is a long requested addition to the platform, and I’m sure welcomed by a host of folks. So I decided to take a look in my local environment to see what the process entails.

There are two primary components to the upgrade: the preupgrade-assistant and the redhat-upgrade-tool.  The procedure is laid out in this Knowledgebase article on the Customer Portal, but the basics are: update the system, run the preupgrade tool to get a report, remediate until you pass, then do the upgrade.

Here’s how it worked out in my environment.

First, if you are running a Satellite server like I am, make sure you check your certificate. The tools are available in a separate child channel for RHEL 6, rhel-x86_64-server-extras-6. I wasn’t able to sync that channel since it wasn’t in the manifest for the current certificate. Once you cut a new certificate in the Customer Portal, you can run a standard sync to pull the channel and the four packages.

[root@ep-sat01 ~]# satellite-sync -c rhel-x86_64-server-extras-6

Now that my Satellite can serve the content, I move over to the target server and start the preupgrade goodness. The tool comes with a command line tool and a web app that you can use to store, examine, and compare reports from multiple hosts. I’m going with that option and going to correct something in the KB article that would make Dan Walsh cry. There is a bugzilla tracker open to add an SELinux policy, but I’m going to add a “works for me” set of commands here.

On the target machine, I’ll add the new Extras channel and install the RPMs.

[root@ep-mgmt01 ~]# rhn-channel --add --channel rhel-x86_64-server-extras-6
 Username: satadmin
[root@ep-mgmt01 ~]# yum -y install preupgrade-assistant preupgrade-assistant-ui preupgrade-assistant-contents

The web app delivers a localhost-only policy, so I’ll copy the supplied “public” config in its place. You could just as easily modify the policy and include a hostname.

[root@ep-mgmt01 ~]# cd /etc/httpd/conf.d/
[root@ep-mgmt01 conf.d]# cp 99-preup-httpd.conf 99-preup-httpd.conf.local
[root@ep-mgmt01 conf.d]# cp 99-preup-httpd.conf.public 99-preup-httpd.conf
 cp: overwrite `99-preup-httpd.conf'? y

Now for the security parts: First I’ll open port 8099 on the firewall which is where the web app listens, then register that port as an http port with SELinux, and finally change the context on the path the web app uses.

[root@ep-mgmt01 conf.d]# iptables -I INPUT -m state --state NEW -p tcp --dport 8099 -j ACCEPT
[root@ep-mgmt01 conf.d]# semanage port -a -t http_port_t -p tcp 8099
[root@ep-mgmt01 conf.d]# chcon -R system_u:object_r:httpd_sys_content_rw_t:s0 /var/lib/preupgrade/

Now, I’m ready to run the tool. Since I’ve gone through the trouble to set up the web app, I’ll upload the results directly to the app from the command line run. I didn’t bother setting up a NameVirtualHost for the server hosting the web app, so you’ll see the IP address in the command instead of the hostname. Check the help (preupg -h) for more options.

[root@ep-mgmt01 ~]# preupg -u http://localhost:8099/submit/
 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
 Gathering logs used by preupgrade assistant:
 All installed packages : 01/10 ...finished (time 00:01s)
 All changed files : 02/10 ...finished (time 03:28s)
 Changed config files : 03/10 ...finished (time 00:00s)
 All users : 04/10 ...finished (time 00:00s)
 All groups : 05/10 ...finished (time 00:00s)
 Service statuses : 06/10 ...finished (time 00:00s)
 All installed files : 07/10 ...finished (time 00:03s)
 All local files : 08/10 ...finished (time 00:04s)
 All executable files : 09/10 ...finished (time 00:01s)
 RedHat signed packages : 10/10 ...finished (time 00:00s)
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 -r /root/preupgrade-results/preupg_results-*.tar.gz .
Report submitted successfully. You can inspect it at http://localhost:8099/1/detail/

Ok, successful report run, and you can see where the tool uploaded the reports to the web app. Let’s hit the web app and see what I got. First thing you’ll be asked is if you want to set up a user. I’m going to skip this for now; you can actually set up a user in the UI later.

'Welcome to Preupgrade Assistant UI'

Click ‘Disable Authentication’ and move on to the next screen, where you’ll see my first run posted.

There’s my local system ep-mgmt01.lab.dlt.com, with a quick summary of status. You can see that the tool thinks I have a high risk level, with six items that require some action and seven more that we need to review. I will need to remediate these to lower our risk and increase the chance of a successful upgrade. Clicking anywhere on the row brings us to the Test Summary section, where we can see the scores for the groups of test run against the system.

'List of runs - completed'


Let’s take a look at the Packages groups, since I can see three different things that need action there. The Status column shows a nice graphical view of the line items we should dig into.



I’ll pick the first item in the list, “Packages not signed by Red Hat”.

'Action Detail - EPEL'


Ok, nice write up on what the problem is and the reasoning behind the severity level.  There’s a link to the list of unsigned packages so I’ll click that to see what the tool picked up.



I know that there are a few packages on the system from EPEL from a project that I don’t care about, so I won’t be taking any action here. There are other things that the tool can help with and will make suggestions for.  Let’s look at the “optional channel problems” line.



Here the tool provides a command line option that we can pass to the upgrade process to fix this for us. After you remediate issues, you can rerun the scan and do comparisons against previous reports.

To run this on other systems in the environment, I only need to install the tool and content, then run in upload mode to the web app I set up.

[root@ep-ipa01 ~]# yum -y install preupgrade-assistant preupgrade-assistant-contents
[root@ep-ipa01 ~]# preupg -u http://ep-mgmt01:8099/submit/


You can see below that my IdM server has some major issues with in-place upgrades for RHEL 7.


And that’s it for the preupgrade assistant. It’s a good little tool with a nice web interface, useful for estimating your level of effort for moving to RHEL 7. Next time we’ll look at an actual upgrade.

Matt Micene Solutions Architect, DLT

Matt Micene is a Solutions Architect and lead engineer for DLT Solutions. He has over 10 years of experience in information technology, ranging from Solaris and Linux architecture and system design to data center design to long, coffee filled nights of system maintenance for various web-based service companies. In his current role, Matt advises customers in the pre-implementation stage, with the adoption and understanding of technologies, such as cloud computing and virtualization. He assists public sector customers with selecting the best building blocks to create environments supporting their missions. A strong advocate for open source, Matt is also a Red Hat Certified Architect (RHCA) and was named RHCE of the Year in 2010.