How to migrate Red Hat Enterprise Linux 5 to Red Hat Enterprise Linux 7 with the Preupgrade Assistant

Solution Verified - Updated 5 Aug 2024

Environment

Red Hat Enterprise Linux 5.11 to Red Hat Enterprise Linux 7
Red Hat Subscription Manager (RHSM)

Issue

How do I do migrate from Red Hat Enterprise Linux 5 to Red Hat Enterprise Linux 7?
How do I use the Preupgrade Assistant to migrate from Red Hat Enterprise Linux 5 to Red Hat Enterprise Linux 7?

Resolution

Overview

This document describes how administrators can migrate from a Red Hat Enterprise Linux 5 system to a target Red Hat Enterprise Linux 7 system with the help of the Kickstart file, which contains the data preserved from the Red Hat Enterprise Linux 5 system.

NOTE:

The following information has been provided by Red Hat, but is outside the scope of the posted This content is not included.Service Level Agreements and support procedures.
Red Hat currently supports only upgrades from latest Red Hat Enterprise Linux 6 to latest Red Hat Enterprise Linux 7 for specific/targeted use cases only.
How do I upgrade from Red Hat Enterprise Linux 6 to Red Hat Enterprise Linux 7?
Migration by using the Preupgrade Assistant is not a fully automated solution. Its purpose is to facilitate the migration to a new major version of Red Hat Enterprise Linux, not to automate it. It requires an experienced administrator to review the assessment report as well as the generated Kickstart file, and to take necessary actions based on the instructions.
This is only available for Red Hat Enterprise Linux 5 systems that are using the Subscription Manager.
Customers currently using Satellite 5.x environments will not be able to access this package due to RHN / RHSM conflicts.
You can convert to the Subscription Manager with the following KCS
How to migrate a Red Hat Enterprise Linux System from RHN Classic to RHSM.

The migration process consists of the following steps:
1. Install the Preupgrade Assistant
2. Run the Preupgrade Assistant
3. Generate Kickstart with the Preupgrade Assistant
4. Install Red Hat Enterprise Linux 7 with the Preupgrade Assistant Kickstart

# Step 1: Install the Preupgrade Assistant The Preupgrade Assistant (the `preupg` command) lets you check for any potential problems you might encounter with a Red Hat Enterprise Linux 5 to Red Hat Enterprise Linux 7 migration and it will help you assess your chances of its success.

NOTE: You can (and should) run the Preupgrade Assistant multiple times to address anything that could cause problems during the migration. The Preupgrade Assistant will not affect your installed system.

The Preupgrade Assistant does the following:

Assesses the system for possible migration limitations.
Provides a report with the results.
Provides data that could be used for the migration.
Provides post-migration scripts to finish more complex issues after the migration.

Perform the following steps to install the Preupgrade Assistant:

1. Enable the correct repository: Enable the repository that contains the preupgrade-assistant and preupgrade-assistant-el5toel7-data packages via Red Hat Subscription Management:

# subscription-manager repos --enable rhel-5-server-rpms

2. Install the preupgrade-assistant packages: The preupgrade-assistant package contains the preupg command and the preupgrade-assistant-el5toel7-data package contains modules with various tests. To install them, type the following:

# yum install -y preupgrade-assistant preupgrade-assistant-el5toel7-data

# Step 2: Run the Preupgrade Assistant 1\. **Run the** `preupg` **command to perform the assessment of the system**

  # preupg
  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)
     ...
  |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://example.com:8099/submit/ -r /root/preupgrade-results/preupg_results-*.tar.gz .

2. View the assessment results
When the Preupgrade Assistant scans your system, each performed test is listed on the screen and followed by an exit code that describes its result. It also produces results files, which you can review in the following ways:

command line: The exit code of each test and the assessment summary are displayed on the screen. Scroll back through the results to get a sense of how each test finished. You can see the exit codes only, and not the descriptions of the issues.
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 a system that has a graphical browser to view the file. An example of viewing the file by using the firefox command:
# firefox file:///root/preupgrade/result.html

3. Check the exit codes
The result shown for each test includes an exit code. Possible exit codes of the tests performed by preupg are:

Exit code	Explanation
PASS	Everything is fine. You should be able to proceed to the migration when all exit codes are listed as PASS.
FAIL	Extreme migration risks. Migration is not possible.
NEEDS_ACTION	High migration risk. Some administrator action is needed before running the migration.
NEEDS_INSPECTION	Lower or medium risks. This exit code does not necessarily mean the migration 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 migration 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.

Content from this.is.an.invisible.element.without.which.there.is.no.space.between.the.table.and.the.sentence.below is not included.

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

# Step 3: Generate a ***Kickstart*** file with the Preupgrade Assistant With the Preupgrade Assistant assessment completed and all issues addressed, the next step is to generate a ***Kickstart*** file which will be used for the migration.

1. Run the preupg-kickstart-generator command to generate the Kickstart file:

# preupg-kickstart-generator 
The Preupgrade Assistant generates a kickstart file in '/root/preupgrade/kickstart/preupgrade.ks'.
The Kickstart file contains:
- users with UID/GID which you should create on Red Hat Enterprise Linux 7 system.
- the partitioning layout which was used on this system
- the package set which was installed on this system.
- the firewall rules which were enabled on this system.
The Kickstart file is pre-generated from this system and is not to be used directly for 
the installation of Red Hat Enterprise Linux 7.
The Kickstart file needs to be modified by the administrator.
These directories exist on the migration system:
- /root/preupgrade/preupg_results-170125035227/cleanconf - configuration files which can be used on the migrated system.
- /root/preupgrade/preupg_results-170125035227/dirtyconf - configuration files which need to be clarified by the administrator.

2. Review and update the Kickstart file: It is strongly recommended to go through the generated Kickstart file (/root/preupgrade/kickstart/preupgrade.ks) and do at least one update to it - uncomment and change the root password. Read the following list of the Kickstart sections to be able to identify what changes to Kickstart are needed before using it for the system migration.

Root password

Without uncommenting this line (by deleting the # sign at the beginning of the line) the system migration would not be automated , and the root password would be requested interactively.
There are two options for entering the password: either as a plain text (--plaintext) or as a SHA-512 hash of the password (--isCrypted).

# Root password
#rootpw --plaintext <password_placeholder>

Firewall

The Kickstart file contains firewall rules as defined on the Red Hat Enterprise Linux 5 system. They are enabled in Kickstart by default, but firewalld itself is not started in Red Hat Enterprise Linux 7 automatically.

# Firewall configuration
firewall --enabled --service=ssh

Repositories

The Kickstart file contains repositories which are enabled on the Red Hat Enterprise Linux 5 system. The rows with repositories are commented out by default and the administrator has to decide if they will be enabled (by deleting the # sign at the beginning of the line) during the Red Hat Enterprise Linux 7 installation.
An example of the above mentioned part in Kickstart:

#repo --name="rhel-supplementary" --baseurl=http://download.devel.redhat.com/released/RHEL-5-Server-Supplementary/U11/$basearch/os
#repo --name="rhel" --baseurl=http://download.eng.brq.redhat.com/pub/rhel/released/RHEL-5-Server/U11/$basearch/os/Server

Users

The Kickstart file contains users' accounts which exist on the Red Hat Enterprise Linux 5 system and are not system users like Apache, ftp, and other system users. They are commented out by default.
Kickstart users' accounts are only local and do not contain passwords. The hash algorithm was changed from MD5 used in Red Hat Enterprise Linux 5 to SHA-512 in Red Hat Enterprise Linux 7 . If you want, add --password= password at the end to log in to the system with a password.

#user --homedir=/home/foo --name=test --shell=/bin/bash --uid=500
#user --homedir=/home/bar --name=test --shell=/bin/bash --uid=501

Groups

The Kickstart file contains groups which exist on the Red Hat Enterprise Linux 5 system and the administrator has to uncomment them (by deleting the # sign at the beginning of the line) to add them to the Red Hat Enterprise Linux 7 system.

#group --name=pcap --gid=77
#group --name=tester --gid=500

Partitioning

The preupg-kickstart-generator command gathers the Red Hat Enterprise Linux 5 system partitioning layout and prepares commented out commands in the Kickstart file (part, volgroup, logvol, raid) that would replicate the layout in Red Hat Enterprise Linux 7. Be aware that the size of the partitions used for Red Hat Enterprise Linux 5 might not be sufficient for Red Hat Enterprise Linux 7. Also the drive identifier (for example, vda or sda) might not be the same in Red Hat Enterprise Linux 7. It is up to the administrator whether to use these specific partitioning commands. By default, an automatic partitioning option is utilized during the Red Hat Enterprise Linux 7 installation (autopart).

An example of a partitioning layout:

autopart
# Partition clearing information
clearpart --all
# Disk partitioning information
#part /boot --ondisk=hda --size=101
#part pv.01 --size=10134
#volgroup VolGroup00 --pesize=4096 pv.01
#logvol /  --size=6112 --name=LogVol00 --vgname=VolGroup00
#logvol swap  --size=4000 --name=LogVol01 --vgname=VolGroup00

3. Validate Kickstart before the Red Hat Enterprise Linux 7 installation
Before you use the preupgrade.ks file for the Red Hat Enterprise Linux 7 installation, it has to be reviewed and validated.

To validate it, use the preupg_ksvalidator command from the preupgrade-assistant package:

# preupg_ksvalidator /root/preupgrade/kickstart/preupgrade.ks

# Step 4: Install Red Hat Enterprise Linux 7 with the Preupgrade Assistant Kickstart

Follow the instructions in How to perform a Kickstart installation

Relevant links:

How do I upgrade from Red Hat Enterprise Linux 6 to Red Hat Enterprise Linux 7
How do I migrate from Red Hat Enterprise Linux 5 to Red Hat Enterprise Linux 7
Automating the installation with Kickstart
Kickstart installation
This content is not included.Download the preupgrade RPMs from the RHEL 5 Beta Channel search:preupgrade

FAQ

Are services enabled in Red Hat Enterprise Linux 5 enabled also in Red Hat Enterprise Linux 7?

Currently this feature is not provided.

Why is the migration not fully automated?

Migrations require some level of review by a system administrator as it is impossible to predict all of the ways a system might be uniquely configured or modified.

Are runlevels migrated?

No, they are not. There is a big change between RHEL 5 and RHEL 7. In RHEL 5 the runlevel command is used , whereas in RHEL 7 it is systemctl set-default runlevel<targetname>.target. For further details, see Overview of systemd for RHEL 7.

Known issues

The released version of the Preupgrade Assistant v2.3.1 (and its modules) for Red Hat Enterprise Linux 5 is the final version, and no new versions are planned to be released. In case you find any issues, see Known issues for migration from Red Hat Enterprise Linux 5 to Red Hat Enterprise Linux 7.

Product(s)

Red Hat Enterprise Linux

Category

Migrate

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.