Customizing your Red Hat Enterprise Linux in-place upgrade

---

This article describes how to use custom repositories and how to create custom actors when upgrading from Red Hat Enterprise Linux 7 to Red Hat Enterprise Linux 8, from Red Hat Enterprise Linux 8 to Red Hat Enterprise Linux 9, and from Red Hat Enterprise Linux 9 to Red Hat Enterprise Linux 10 by using the Leapp utility.

For information about how to customize an in-place upgrade from Red Hat Enterprise Linux 6 to Red Hat Enterprise Linux 7, see How to create custom Preupgrade Assistant modules for upgrading from RHEL 6 to RHEL 7.

Using custom repositories for an in-place upgrade

During an in-place upgrade, you can use custom repositories in one of the following ways:

• As additional repositories, together with repositories accessed through Red Hat Subscription Manager (RHSM). For example, a repository with third-party drivers that are not provided by Red Hat

• As the only repositories used for an in-place upgrade, for example, on a detached system. In this case, your custom repositories must provide the RHEL content.

IMPORTANT: Ensure that you have the most recent packages in repositories providing the RHEL content. For this reason, you cannot use binary DVDs.

Configuring custom repositories

You can configure custom repositories for use by Leapp in two ways. You can use either of the two approaches or combine both:

• Create the /etc/leapp/files/leapp_upgrade_repositories.repo file, and add one or more repositories. All repositories configured in this file are used only by Leapp during an in-place upgrade. Use this approach if you want to define custom repositories only for the purpose of an in-place upgrade.

  Refer to How to upgrade a system with "leapp" while also upgrading EPEL or Puppet Labs packages for an example.

• Use repositories configured in the /etc/yum.repos.d/ directory. This is the standard directory for configuring repositories on a RHEL system, which are used, for example, by the YUM or DNF utility. You can use previously configured repositories or create one or more new .repo files in this directory. If you want to use any of the repositories configured in /etc/yum.repos.d/ for the upgrade, enable each of the selected repositories explicitly when executing the leapp command.

  • In the preupgrade phase:

    leapp preupgrade --enablerepo repository_id1 --enablerepo repository_id2 ...
    

  • During the in-place upgrade:

    leapp upgrade --enablerepo repository_id1 --enablerepo repository_id2 ...
    

The minimum content for each repository in a .repo file is as follows:

[repository_id]
name=repository_name
baseurl=repository_url

For more information about repository configuration, see Setting [repository] Options in the RHEL 7 System Administrator's Guide or the [repository] OPTIONS section in the dnf.conf(5) man page.

IMPORTANT: Ensure that all custom repository IDs are unique and that they do not conflict with repositories accessed through RHSM.

NOTE: Leapp ignores the enabled directives set for custom repositories in any of the .repo files. Leapp uses repositories from the /etc/yum.repos.d/ directory if they are enabled through the --enablerepo option of the leapp command, and automatically all repositories configured in the /etc/leapp/files/leapp_upgrade_repositories.repo file.

For examples on how to configure custom repositories for an in-place upgrade, see the How to in-place upgrade an offline / disconnected RHEL 7 machine to RHEL 8 with Leapp? or How to in-place upgrade an offline / disconnected RHEL 8 machine to RHEL 9 with Leapp? solution article.

Performing an in-place upgrade without Red Hat Subscription Manager

An in-place upgrade requires different preparation steps if you do not want to use Red Hat Subscription Manager (RHSM).

For more information about performing the in-place upgrade, see the official product documentation:

• Upgrading from RHEL 7 to RHEL 8
• Upgrading from RHEL 8 to RHEL 9
• Upgrading from RHEL 9 to RHEL 10

Procedure

1. Ensure that you have enabled at minimum the following repositories on your source system:

   • For the upgrade from RHEL 7 to RHEL 8:

     • RHEL 7 Base
     • RHEL 7 Extras

   • For upgrades from RHEL 8 and later versions:

     • BaseOS
     • AppStream

2. Configure custom repositories. Ensure that your custom repositories include at least the following repositories on the target system:

   • BaseOS
   • AppStream

   IMPORTANT: Сustom repositories must be up-to-date with the content of the RHEL system of the target OS release. Note that the Leapp utility does not check whether the content in these repositories on the source system corresponds to the expected content version of the target RHEL system. This applies also to ISO repositories. Therefore, you must verify that the content of any custom repository used during the upgrade is valid. For the list of the supported target OS releases for your installed system, see Supported in-place upgrade paths for Red Hat Enterprise Linux.

3. In the official product documentation, complete the Preparing a RHEL system for the upgrade procedure, skipping the steps relevant for systems that use RHSM, and follow the rest of the document. Make sure to execute the leapp command with the --no-rhsm option at every stage. If you are upgrading by using the RHEL ISO image, add the --iso option at every stage.

   • In the preupgrade phase:

     leapp preupgrade --no-rhsm
     

   • During the in-place upgrade:

     leapp upgrade --no-rhsm
     

   If your custom repositories on the RHEL target system content are configured in the /etc/yum.repos.d/ directory, include the --enablerepo option for each of the repositories you want to use for the upgrade to the leapp commands.
   
   

Handling the migration of your custom and third-party applications

IMPORTANT: Red Hat Test Coverage and Support does not support migration of custom and third-party applications installed on your system during the upgrade process. Contact your ISV for support and instructions.

The simplest way to handle custom and third-party applications during the in-place upgrade is to remove these applications before the upgrade and install them after. However, if you prefer not to temporarily remove these applications, there are several ways to handle the migration of custom and third-party applications installed on your system during the upgrade process:

• Providing custom repositories with builds for the target OS

• Excluding RPM packages from the upgrade process

• Extending the upgrade functionality using Leapp custom actors

Providing custom repositories with builds for the target OS

In an ideal scenario, all custom applications should have builds available for the target RHEL OS release. If YUM or DNF repositories with such packages are used during the upgrade process, then the original packages are automatically updated if the following criteria are met:

• The target packages have proper attributes (Provides, Obsoletes, Requires, scriptlets, and other attributes). In this case, YUM or DNF can handle the target packages as any other RPM packages for update.

• All required packages are available during the upgrade process. In this case, dependencies are not broken for these packages.

For more information, see Using custom repositories for an in-place upgrade.

NOTE: Make sure to enable any additional target RHEL OS repositories that are required to satisfy dependencies for the target packages.

If you need to perform any steps in addition to the default upgrade RPM transaction, follow the procedure described in Extending the upgrade functionality using Leapp custom actors.

Excluding RPM packages from the upgrade process

IMPORTANT: Excluding RPM packages from the upgrade process might result in a broken upgrade process or a malfunctioning system. Red Hat does not support such cases.

NOTE: Custom and third-party packages are not automatically removed during the upgrade unless they cause a dependency issue with the target RHEL OS. For example:

• An RPM package requires libXY version 1.2 or older, however, libXY on the target system has version 1.3. The package is removed because its dependencies are broken for the target system.

• An RPM package requires the python2-foo package, however, only the python3-foo package is available on the target system. The package is removed because there is no required package present on the target system.

If you do not want a set of packages to be upgraded or removed during the upgrade process, you can exclude such packages by specifying the exclude configuration option in the /etc/dnf/dnf.conf file.

To specify multiple packages to exclude, enter packages in a comma-separated list. For example:

[main]
exclude=package-name1,package-name2,package-name3,...

Replace package-name1, package-name2, package-name3, … with the names of packages that you want to exclude during the upgrade process.

If any excluded packages must be removed or upgraded during the upgrade process, the in-place upgrade is halted and an error message is generated.

Note that this process can lead to the upgraded system being composed of a mixture of old and new packages. Any old RHEL packages present after the upgrade must be removed, which can lead into the removal of custom and third-party packages. For more information, see Performing post-upgrade tasks in the Upgrading from RHEL 7 to RHEL 8 guide or Performing post-upgrade tasks in the Upgrading from RHEL 8 to RHEL 9 guide.

Extending the upgrade functionality using custom leapp actors

IMPORTANT: Red Hat does not support custom Leapp actors.

You can migrate third-party and custom applications installed on your system by extending the current in-place upgrade functionality using custom Leapp actors. Actors specify particular actions to be performed by Leapp during the upgrade, for example, reconfiguring an application or installing a specific hardware driver. Note that providing additional instructions to Leapp through custom actors is the only way to migrate third-party and custom applications if the applications require additional actions besides regular RPM transactions during the upgrade process.

Example cases that require creating custom actors:

• I need to enable specific repositories or install specific packages during the upgrade process, for example, based on the configuration of my system.

• My system uses third-party drivers that need to be included in the upgrade or target initramfs to be able to boot correctly, for example, when storage drivers are required.

• I want the system to be configured differently from the current results to reach an optimal state.

• Some actions I need to do after the upgrade require system reboot to take effect. Performing such actions during the upgrade process could reduce the number of reboots.

NOTE: Actors executed inside the upgrade environment after the system is rebooted during the in-place upgrade as described in step 2 of Performing an in-place upgrade from RHEL 7 to RHEL 8 or Performing an in-place upgrade from RHEL 8 to RHEL 9, might experience certain limitations such as missing network connectivity or limitations caused by containerization (for example, systemd is not running).

To create a custom actor, follow the procedure described in Creating Leapp custom actors.

Creating Leapp custom actors

IMPORTANT: Red Hat does not support custom actors.

Procedure

1. Install the necessary packages:

   • For RHEL 7, install the leapp-upgrade and snactor packages from the RHEL 7 Extras repository:

     # yum install leapp-upgrade snactor
     

   • For RHEL 8 and later, install the packages from the RHEL AppStream repository:

     # dnf install leapp-upgrade snactor
     

     IMPORTANT: On RHEL 9, to install the snactor package, you must first enable the CRB repository.

2. Change to the directory where a new Leapp repository for custom actors should be created:

   # cd /usr/share/leapp-repository/custom-repositories/
   

3. Create a new Leapp repository for your custom actors:

   # snactor repo new repository_name
   

4. Create the following symlink:

   # ln -s /usr/share/leapp-repository/custom-repositories/repository_name /etc/leapp/repos.d/
   

   The symlink ensures that Leapp is able to work with the new repository.

5. Change to the directory of the new Leapp repository:

   # cd /usr/share/leapp-repository/custom-repositories/repository_name/
   

6. Link the new Leapp repository to the main Leapp upgrade repository:

   # snactor repo link --path /usr/share/leapp-repository/repositories/system_upgrade/el<source>toel<target>/
   

   Replace source with the major version of the source system and target with the major version of the target system you want to upgrade to, for example, el7toel8.

   This ensures that your custom actors can consume messages produced by actors provided by Red Hat, and that actors provided by Red Hat can consume messages produced by your custom actors. Your custom actors can also use the shared library functions, models, topics, and tags provided by Red Hat. Avoid using deprecated Leapp functionality in custom actors. For more information, see Deprecated Leapp functionality.

7. Create a boilerplate of your custom actor:

   # snactor new-actor --tag IPUWorkflowTag actor_name
   

8. Complete the procedure in the Content from leapp-repository.readthedocs.io is not included.How to write an Actor for Leapp Upgrade upstream Leapp guide. For custom content, adjust the following paths:

   • Repository configuration: Create custom repositories in the /etc/leapp/repos.d/<repository_name>/ directory.

   • Repository installation: Install custom repositories to the /usr/share/leapp-repository/custom-repositories/ directory.

For more information about creating custom content, see Content from leapp-repository.readthedocs.io is not included.How to create custom content for IPU.

NOTE: For more information about various examples of actors that cover common situations that you might encounter, see Content from leapp-repository.readthedocs.io is not included.Templates. These examples provide hints for creating custom content.

Additional information

• Content from leapp.readthedocs.io is not included.Best Practices for actor development
  
  

Deprecated Leapp functionality

Over time, some Leapp functionality, such as models, shared library functions, and public APIs, might be deprecated. Deprecated Leapp functionality remains supported until the indicated end of support date, usually six months after the deprecation announcement. After the end of support date, deprecated functionality might be removed from Leapp, causing custom actors that use that functionality to break.

The table below lists functionality that is deprecated and should not be used in custom actors.

Functionality type	Functionality name	Details	End of support
Model	GrubDevice	Deprecated because the current implementation is not reliable. GRUB device detection is now in the shared grub library. Use the leapp.libraries.common.grub.get_grub_device() function instead.	April 2021
Model	UpdateGrub	Deprecated because the current implementation is not reliable. GRUB device detection is now in the shared grub library. Use the leapp.libraries.common.grub.get_grub_device() function instead.	April 2021
Model	TMPTargetRepositoriesFacts	Deprecated because this model was not intended for customer use.	April 2021
Shared library function	leapp.libraries.common.testutils.logger_mocked.warn()	The logging.warn method has been deprecated in Python since version 3.3. Use the warning method instead.	April 2021
Model	RequiredTargetUserspacePackages	Deprecated because the new solution has been designed. Use the TargetUserspacePreupgradeTasks instead (see the install_rpms field).	April 2022
Model	RequiredUpgradeInitramPackages	Deprecated because the new solution around the upgrade initramfs has been designed. Use the TargetUserspaceUpgradeTasks instead (see the install_rpms field).	April 2022
Model	UpgradeDracutModule	Replaced by UpgradeInitramfsTasks (see the include_dracut_modules field).	April 2022
Model	InitrdIncludes	Deprecated because the new solution around the target initramfs (the initramfs created for the upgraded system) has been designed. Use the TargetInitramfsTasks instead (see the include_files field).	April 2022
Shared library function	leapp.libraries.common.utils.apply_yum_workaround()	Deprecated in favor of the new generic solution. Use the DNFWorkaround message instead.	Oct 2022
Reporting primitives	leapp.reporting.Flags	The Flags report primitive has been deprecated in favor of the more general Groups one.	Mar 2023
Reporting primitives	leapp.reporting.Tags	The Tags report primitive has been deprecated in favor of the more general Groups one.	Mar 2023
Model	InstalledTargetKernelVersion	Deprecated in favor of the new solution for handling new changes in RHEL 9.3 and newer releases. Use the InstalledTargetKernelInfo message instead.	Mar 2024
Model Field	GrubInfo.orig_device_name	The GrubInfo message is still valid, but the orig_device_name field has been deprecated because multiple devices can exist on a system. Use GrubInfo.orig_devices instead.	April 2024
Shared library function	leapp.libraries.common.config.version.is_rhel_realtime()	The function has been deprecated because the information cannot be easily determined based on the information inside IPUConfig. Instead, use data in the KernelInfo message in the type field.	April 2024
Shared library function	leapp.libraries.common.grub.get_grub_device()	The function has been deprecated because multiple grub devices can exist on a system. Use the leapp.libraries.common.grub.get_grub_devices() function instead.	April 2024
Model	InstalledRedHatSignedRPM	Replaced by the distribution agnostic DistributionSignedRPM.	April 2025
Shared library function	leapp.libraries.common.config.version.is_rhel_alt()	The function returns only False because RHEL 7 for IBM POWER 9 (little endian), 64-bit ARM, and 64-bit IBM-Z (Structure A) architectures reached End of Life (EOL), and future versions of the leapp-repository package will not support RHEL 7.	April 2026
Shared library function	leapp.libraries.common.config.version.SUPPORTED_VERSIONS	This dictionary has been deprecated because it is not aligned with the redesigned codebase. Use leapp.libraries.common.config.version.is_supported_version() or IPUConfig.supported_upgrade_paths functionality instead.	April 2026
Model	InstalledUnsignedRPM	Replaced by the distribution agnostic ThirdPartyRPM model.	April 2026

Additional information

• Content from leapp.readthedocs.io is not included.Developer documentation for Leapp deprecation
• Content from leapp-repository.readthedocs.io is not included.List of upstream deprecated functionality (leapp-repositories)
• Content from leapp.readthedocs.io is not included.List of upstream deprecated functionality (leapp framework)

SBR

• Shells

Product(s)

• Red Hat Enterprise Linux

Category

• Upgrade

Components

• leapp

Article Type

• General