In-Place RHEL Upgrades with LEAPP and Red Hat Satellite

From RHEL 7 → 8 and RHEL 8 → 9 at Enterprise Scale

Major OS upgrades are traditionally disruptive: rebuilds, migrations, re-provisioning, and long outages. LEAPP (Linux Experience Application Protection Program) is Red Hat’s official, supported framework for performing in-place major version upgrades on RHEL systems while preserving configuration, data, and system identity.

When combined with Red Hat Satellite (6.11+, recommended 6.13+), LEAPP becomes a repeatable, auditable, fleet-wide upgrade pipeline—critical for enterprises running hundreds or thousands of systems.

This guide covers architecture, preparation, Satellite integration, execution, troubleshooting, rollback realities, and automation, with deep technical detail.

What LEAPP Really Does

LEAPP is not a simple wrapper around dnf.

Internally, LEAPP:

• Inspects the current OS (RPM DB, kernel, drivers, services)
• Runs actors (Python-based checks) grouped into phases
• Builds a RHEL target userspace in /var/lib/leapp
• Boots into a temporary upgrade initramfs
• Switches userspace + kernel
• Replays configuration transformations

Key directories:

/var/log/leapp/           # Logs & reports

/var/lib/leapp/           # Upgrade environment

/etc/leapp/files/         # Answer files & overrides

Supported Upgrade Paths

LEAPP refuses unsupported jumps.

Source         Target

RHEL 7.9 RHEL 8.x (latest supported minor)

RHEL 8.9 RHEL 9.x (certified minor only)

Unsupported:

• 7 → 9 direct
• Non-EUS releases
• Custom kernels
• Non-x86_64 architectures

Always verify with Red Hat’s LEAPP compatibility matrix before starting.

Why Satellite Integration Matters

Using LEAPP without Satellite pulls packages directly from the Red Hat CDN. That’s fine for one system—but risky at scale.

Satellite adds:

• Content Views
• Lifecycle environments (Dev → Test → Prod)
• Air-gapped upgrades
• CVE-controlled promotion
• Auditability

In production environments, LEAPP + Satellite is the only sane approach.

Satellite Preparation

1. Repository Strategy

You must provide both source and target OS repositories simultaneously.

For RHEL 7 → 8:

• RHEL 7 Base
• RHEL 8 BaseOS
• RHEL 8 AppStream
• LEAPP repository for RHEL 7

Enable via Hammer:

# hammer repository-set enable \

  --organization "YourOrg" \

  --product "Red Hat Enterprise Linux Server" \

  --name "Red Hat Enterprise Linux 7 Server (RPMs)" \

  --releasever "7Server"

Repeat for RHEL 8 BaseOS/AppStream and LEAPP.

2. Content View Design

Bad approach:

• Use existing prod Content View
• Mix upgrade and runtime repos

Recommended:

• Dedicated migration Content View
• No third-party repos
• Minimal filters

Example:

RHEL-Migration-CV

├── RHEL7-Base

├── RHEL8-BaseOS

├── RHEL8-AppStream

└── Leapp-RHEL7

Publish and promote only to Library or Dev, not Prod.

3. Activation Keys for Re-Registration

Post-upgrade systems often need clean re-registration.

Create:

• RHEL7-MIGRATION-AK
• RHEL8-POSTUPGRADE-AK

These:

• Attach correct subscriptions
• Enable only approved repos
• Prevent repo drift

Client-Side Preparation

1. Baseline Requirements

Requirement	Why
Latest minor version	LEAPP expects final RPM state
≥2× root FS free	Userspace duplication
No unsupported kernel modules	Upgrade kernel replacement
No EPEL / 3rd-party RPMs	Hard inhibitors

Check space:

# df -h /

2. Install LEAPP Packages

# dnf install leapp \

            leapp-repository \

            leapp-data-rhel \

            --assumeyes

Satellite must supply these RPMs.

3. Pre-Upgrade Scan

# leapp preupgrade

This:

Runs ~200+ checks

Generates structured JSON + text reports

Classifies issues as:

• Inhibitors (hard stop)
• Warnings
• Info

Key report:

/var/log/leapp/leapp-report.txt

Common Inhibitors and Real Fixes

Inhibitor	Remediation
NetworkManager ≥1.22	dnf swap NetworkManager NetworkManager-1.18 ​
firewalld	Remove or mask conflicting rules
Third-party repos	Disable or filter packages
PAM/SSSD	Update configs per report
Disk space	Ensure ≥2x root partition free

Disable third-party repos:

# dnf config-manager --disable \*

# dnf config-manager --enable satellite*

Answer Files (Unattended Upgrades)

Some checks require explicit admin consent.

Create:

/etc/leapp/files/leapp_answerfile

Example:

[confirm]

confirm = True

Without this, LEAPP will block automation.

Performing the Upgrade

# leapp upgrade

# reboot

Phase Breakdown

• Pre-upgrade kernel install
• Initramfs boot
• Target userspace deployment
• RPM DB migration
• Config translation
• GRUB update
• Final reboot
• Boot menu entry:

    RHEL-Upgrade-Initramfs

Typical duration:

Small server: 30–45 min

App-heavy system: 60–90 min

Post-Upgrade Validation (Mandatory)

# cat /etc/redhat-release

# uname -r

# subscription-manager status

# dnf repolist

# dnf update --refresh

Re-register if needed:

# subscription-manager unregister

# subscription-manager clean

# subscription-manager register \

  --org="YourOrg" \

  --activationkey="RHEL8-Key"

Logging & Debugging

File                                 Purpose

/var/log/leapp/leapp-preupgrade.log   Pre-check details

/var/log/leapp/leapp-upgrade.log      Full execution trace

/var/log/dnf.log                       RPM transactions

journalctl -b -1                       Boot before failure

Rollback Reality Check

LEAPP does not support full rollback.

Options:

• Boot old kernel (if preserved)
• Restore VM snapshot
• Rebuild system

This is why snapshots/backups are mandatory.

Fleet Automation with Ansible

Use:

infra.leapp

infra.osupgrade

Workflow:

Precheck → Report → Remediate → Upgrade → Validate

Key pattern:

• Do preupgrade only first
• Fix inhibitors fleet-wide
• Upgrade in waves

Satellite + LEAPP at Scale

• Upgrade Capsules first
• Never upgrade Satellite itself with LEAPP
• Pin Content Views tightly
• Monitor /var/lib/leapp disk usage
• Disable Insights remediation during upgrade

Best Practices Checklist

• Snapshot before upgrade
• Dedicated migration content view
• No third-party repos
• Fix all inhibitors
• Use answer files
• Test in Dev first
• Stagger production waves
• Validate post-upgrade

Final Thoughts

LEAPP transforms major RHEL upgrades from rebuild projects into controlled lifecycle events—but only when combined with Satellite discipline and proper preparation.

Most LEAPP failures are environmental, not tooling-related.

When done right, organizations:

• Upgrade thousands of systems in weeks
• Preserve compliance
• Avoid rebuild downtime
• Standardize OS lifecycles